@aeroswarm/client 0.1.11 → 0.1.13

package/dist/index.d.ts

@@ -1,4 +1,79 @@
-export { AeroReplayClient, AeroSwarm, AeroSwarmOptions, AeroWsClient, DayAvailability, ReplayCallbacks, ReplayHandle, ReplayProgress, ReplayStreamOptions, SourceRow, SubscribeOptions, TrackCache, TrackCallbacks, TrackHistoryPoint, UseAeroTracksResult } from './sdk/index.js';
-export { AeroConnectionStatus, AeroRecoverableError, Bbox, ConfidenceBudget, CurrentTrack, FusedTrackEvent, Position, Protocol, SourceHealthEvent, SourceStatus, StreamEnvelope, TrackSource, TrackStatus, Velocity } 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';
 export { clamp, haversineKm, isInsideBbox, isRenderableTrack, toCurrentTrack } from '@aeroswarm/core/utils';
 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;
+
+export { type MotionFrame, type MotionInput, type MotionOptions, type MotionSample, type MotionScheduler, type TrackMotion, createTrackMotion };

package/dist/index.js

@@ -19,11 +19,13 @@ var AeroWsClient = class {
   lastSeq = -1;
   lastHeartbeat = Date.now();
   heartbeatTimer = null;
+  reconnectTimer = null;
   status = "idle";
   connect(opts, callbacks) {
     this.lastSubscribe = opts;
     this.callbacks = callbacks;
     this.stopped = false;
+    this._clearReconnectTimer();
     this._setStatus("connecting");
     this._connect();
   }
@@ -34,10 +36,27 @@ var AeroWsClient = class {
   disconnect() {
     this.stopped = true;
     this._clearHeartbeatTimer();
-    this.ws?.close();
-    this.ws = null;
+    this._clearReconnectTimer();
+    this._dropSocket();
     this._setStatus("offline");
   }
+  /**
+   * 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() {
+    if (!this.lastSubscribe) return false;
+    this.stopped = false;
+    this.attempt = 0;
+    this._clearHeartbeatTimer();
+    this._clearReconnectTimer();
+    this._dropSocket();
+    this._setStatus("reconnecting");
+    this._connect();
+    return true;
+  }
   getStatus() {
     return this.status;
   }
@@ -46,8 +65,17 @@ var AeroWsClient = class {
     this.status = s;
     this.callbacks.onStatusChange?.(s);
   }
+  /** Close the current socket without letting its onclose schedule a reconnect. */
+  _dropSocket() {
+    const ws = this.ws;
+    this.ws = null;
+    if (!ws) return;
+    ws.onopen = ws.onmessage = ws.onclose = ws.onerror = null;
+    ws.close();
+  }
   _connect() {
     const wsUrl = `${this.url}?token=${encodeURIComponent(this.token)}`;
+    this._dropSocket();
     try {
       this.ws = new WebSocket(wsUrl);
       this.ws.binaryType = "arraybuffer";
@@ -112,12 +140,13 @@ var AeroWsClient = class {
       this._requestSnapshot();
     }
     this.lastSeq = msg.seq;
+    const meta = { serverTime: msg.serverTime, seq: msg.seq };
     switch (msg.type) {
       case "snapshot":
-        this.callbacks.onSnapshot?.(msg.payload.tracks);
+        this.callbacks.onSnapshot?.(msg.payload.tracks, meta);
         break;
       case "track.updated":
-        this.callbacks.onTrackUpdate?.(msg.payload.track);
+        this.callbacks.onTrackUpdate?.(msg.payload.track, meta);
         break;
       case "track.removed":
         this.callbacks.onTrackRemoved?.(msg.payload);
@@ -163,10 +192,18 @@ var AeroWsClient = class {
   _scheduleReconnect() {
     const delay = Math.min(1e3 * 2 ** this.attempt, this.maxReconnectDelay);
     this.attempt++;
-    setTimeout(() => {
+    this._clearReconnectTimer();
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
       if (!this.stopped) this._connect();
     }, delay);
   }
+  _clearReconnectTimer() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
 };
 
 // src/sdk/websocket/replay.ts
@@ -316,6 +353,28 @@ var AeroRestClient = class {
     const qs = search.size ? `?${search.toString()}` : "";
     return this.req("GET", `/v1/tracks/current${qs}`);
   }
+  /** Flight plans received from AFTN feeds (FPL/CHG/DLA/DEP/ARR/CNL folded per flight). */
+  listFlightPlans(params) {
+    const search = new URLSearchParams();
+    if (params?.airportId) search.set("airportId", params.airportId);
+    if (params?.status) search.set("status", params.status);
+    if (params?.callsign) search.set("callsign", params.callsign);
+    if (params?.limit != null) search.set("limit", String(params.limit));
+    const qs = search.size ? `?${search.toString()}` : "";
+    return this.req("GET", `/v1/flight-plans${qs}`);
+  }
+  getFlightPlan(id) {
+    return this.req("GET", `/v1/flight-plans/${encodeURIComponent(id)}`);
+  }
+  /** Raw AFTN messages (every parsed ATS message, newest first — the input
+   *  side of the flight-plan pipeline). */
+  listAftnMessages(params) {
+    const search = new URLSearchParams();
+    if (params?.airportId) search.set("airportId", params.airportId);
+    if (params?.limit != null) search.set("limit", String(params.limit));
+    const qs = search.size ? `?${search.toString()}` : "";
+    return this.req("GET", `/v1/aftn/messages${qs}`);
+  }
   health() {
     return this.req("GET", "/health");
   }
@@ -347,6 +406,38 @@ var AeroGraphQLClient = class {
 
 // src/sdk/cache/index.ts
 import { isRenderableTrack } from "@aeroswarm/core/utils";
+
+// src/shared/label/index.ts
+var LABEL_COLORS = {
+  ARRIVAL: "#FACC15",
+  // yellow
+  DEPARTURE: "#22C55E",
+  // green
+  GROUND_VEHICLE: "#3B82F6",
+  // blue
+  LOST: "#FFFFFF",
+  // white
+  UNKNOWN: "#FFFFFF"
+  // white — no flight plan
+};
+function getLabelCategory(track) {
+  if (track.status === "lost") return "LOST";
+  if (track.targetType === "vehicle") return "GROUND_VEHICLE";
+  switch (track.flightPlan?.phase) {
+    case "ARRIVAL":
+      return "ARRIVAL";
+    case "DEPARTURE":
+      return "DEPARTURE";
+    default:
+      return "UNKNOWN";
+  }
+}
+function withLabel(track) {
+  const labelCategory = getLabelCategory(track);
+  return { ...track, labelCategory, labelColor: LABEL_COLORS[labelCategory] };
+}
+
+// src/sdk/cache/index.ts
 var TypedEmitter = class {
   listeners = /* @__PURE__ */ new Map();
   on(event, fn) {
@@ -360,15 +451,18 @@ var TypedEmitter = class {
 };
 var TrackCache = class extends TypedEmitter {
   tracks = /* @__PURE__ */ new Map();
+  /** 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) {
+    const merged = withLabel({ ...this.tracks.get(track.trackId), ...track });
     if (track.status === "lost") {
       this.tracks.delete(track.trackId);
       this.emit("removed", { trackId: track.trackId });
-      return;
+      return merged;
     }
-    const merged = { ...this.tracks.get(track.trackId), ...track };
     this.tracks.set(track.trackId, merged);
     this.emit("update", merged);
+    return merged;
   }
   applyRemoved(ev) {
     this.tracks.delete(ev.trackId);
@@ -377,9 +471,11 @@ var TrackCache = class extends TypedEmitter {
   applySnapshot(tracks) {
     this.tracks.clear();
     for (const t of tracks) {
-      if (isRenderableTrack(t)) this.tracks.set(t.trackId, t);
+      if (isRenderableTrack(t)) this.tracks.set(t.trackId, withLabel(t));
     }
-    this.emit("snapshot", Array.from(this.tracks.values()));
+    const all = Array.from(this.tracks.values());
+    this.emit("snapshot", all);
+    return all;
   }
   getAll() {
     return Array.from(this.tracks.values());
@@ -472,15 +568,15 @@ var AeroSwarm = class _AeroSwarm {
             this._status = s;
             callbacks.onStatusChange?.(s);
           },
-          onSnapshot: (tracks) => {
-            this.cache.applySnapshot(tracks);
+          onSnapshot: (tracks, meta) => {
+            const labeled = this.cache.applySnapshot(tracks);
             this._lastUpdateAt = Date.now();
-            callbacks.onSnapshot?.(tracks);
+            callbacks.onSnapshot?.(labeled, meta);
           },
-          onTrackUpdate: (track) => {
-            this.cache.applyUpdate(track);
+          onTrackUpdate: (track, meta) => {
+            const labeled = this.cache.applyUpdate(track);
             this._lastUpdateAt = Date.now();
-            callbacks.onTrackUpdate?.(track);
+            callbacks.onTrackUpdate?.(labeled, meta);
           },
           onTrackRemoved: (ev) => {
             this.cache.applyRemoved(ev);
@@ -499,15 +595,23 @@ var AeroSwarm = class _AeroSwarm {
       return () => this.wsClient.disconnect();
     },
     updateFilter: (opts) => this.wsClient.updateFilter(opts),
+    /** 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: () => this.wsClient.reconnect(),
     stream: (opts) => {
       const queue = [];
-      let resolve = null;
+      let resolve2 = null;
       let done = false;
       this.wsClient.connect({ encoding: "json", ...opts }, {
-        onTrackUpdate: (t) => {
-          if (resolve) {
-            resolve({ value: t, done: false });
-            resolve = null;
+        onSnapshot: (tracks) => {
+          this.cache.applySnapshot(tracks);
+        },
+        onTrackUpdate: (raw) => {
+          const t = this.cache.applyUpdate(raw);
+          if (resolve2) {
+            resolve2({ value: t, done: false });
+            resolve2 = null;
           } else queue.push(t);
         },
         onStatusChange: (s) => {
@@ -520,7 +624,7 @@ var AeroSwarm = class _AeroSwarm {
             if (queue.length) return Promise.resolve({ value: queue.shift(), done: false });
             if (done) return Promise.resolve({ value: void 0, done: true });
             return new Promise((r) => {
-              resolve = r;
+              resolve2 = r;
             });
           },
           return: async () => {
@@ -545,6 +649,17 @@ var AeroSwarm = class _AeroSwarm {
       return this.trpc.tracks.history.query(input);
     }
   };
+  /** Flight plans received from AFTN feeds. Live tracks that correlate with a
+   *  plan (Mode-S address, else callsign) also carry `track.flightPlan`. */
+  flightPlans = {
+    list: (input) => this.rest.listFlightPlans(input).then((r) => r.data.flightPlans),
+    get: (id) => this.rest.getFlightPlan(id).then((r) => r.data.flightPlan)
+  };
+  /** Raw AFTN/ATS messages received by AFTN feeds — the input side of the
+   *  flight-plan pipeline (newest first, capped by the service). */
+  aftn = {
+    messages: (input) => this.rest.listAftnMessages(input).then((r) => r.data.messages)
+  };
   sources = {
     /** Registers a source and returns its token, tied to `airportId` — a
      *  source is a sensor physically at one airport, so this is required.
@@ -665,19 +780,330 @@ var AeroSwarm = class _AeroSwarm {
   disconnect() {
     this.wsClient.disconnect();
   }
+  reconnect() {
+    return this.wsClient.reconnect();
+  }
 };
 
 // src/shared/utils/index.ts
 import { isRenderableTrack as isRenderableTrack2, haversineKm, isInsideBbox, toCurrentTrack, clamp } from "@aeroswarm/core/utils";
+
+// src/shared/motion/index.ts
+var KT_TO_MS = 0.514444;
+var M_PER_DEG = 111320;
+var MAX_PLAUSIBLE_KT = 1500;
+var OFFSET_WINDOW = 20;
+var ALT_EPSILON_FT = 10;
+var HEADING_EPSILON_DEG = 0.5;
+var SURFACE_ALT_FT = 150;
+var clamp01 = (x) => x < 0 ? 0 : x > 1 ? 1 : x;
+var smoothstep = (x) => {
+  const c = clamp01(x);
+  return c * c * (3 - 2 * c);
+};
+var wrapDeg = (d) => ((d + 180) % 360 + 360) % 360 - 180;
+var norm360 = (d) => (d % 360 + 360) % 360;
+var cosLat = (lat) => Math.max(0.01, Math.cos(lat * Math.PI / 180));
+function validHeading(h) {
+  return h != null && Number.isFinite(h) && h >= 0 && h <= 360 ? h % 360 : null;
+}
+function move(lat, lon, bearingDeg, distM) {
+  const rad = bearingDeg * Math.PI / 180;
+  const dLat = distM * Math.cos(rad) / M_PER_DEG;
+  const dLon = distM * Math.sin(rad) / (M_PER_DEG * cosLat(lat + dLat / 2));
+  return { lat: lat + dLat, lon: lon + dLon };
+}
+function distanceM(aLat, aLon, bLat, bLon) {
+  const dy = (bLat - aLat) * M_PER_DEG;
+  const dx = (bLon - aLon) * M_PER_DEG * cosLat((aLat + bLat) / 2);
+  return Math.hypot(dx, dy);
+}
+var headingChanged = (a, b) => a === null || b === null ? a !== b : Math.abs(wrapDeg(a - b)) > HEADING_EPSILON_DEG;
+var altitudeChanged = (a, b) => a === null || b === null ? a !== b : Math.abs(a - b) >= ALT_EPSILON_FT;
+var defaultIsSurface = (t) => t.targetType === "vehicle" || t.altitudeFt != null && t.altitudeFt <= SURFACE_ALT_FT;
+function resolve(o) {
+  return {
+    blendMs: o.blendMs ?? 1500,
+    headingSmoothMs: o.headingSmoothMs ?? 800,
+    maxExtrapolateMs: o.maxExtrapolateMs ?? { air: 2e4, surface: 8e3 },
+    minMovingKt: o.minMovingKt ?? 5,
+    snapDistanceM: o.snapDistanceM ?? 5e3,
+    frameHz: o.frameHz ?? 30,
+    epsilonM: o.epsilonM ?? 0.5,
+    extrapolate: o.extrapolate ?? true,
+    isSurface: o.isSurface ?? defaultIsSurface,
+    clock: o.clock ?? Date.now,
+    scheduler: o.scheduler
+  };
+}
+function defaultScheduler() {
+  const g = globalThis;
+  if (typeof g.requestAnimationFrame === "function" && typeof g.cancelAnimationFrame === "function") {
+    return {
+      request: (cb) => g.requestAnimationFrame(cb),
+      cancel: (h) => g.cancelAnimationFrame(h)
+    };
+  }
+  return {
+    request: (cb) => setTimeout(() => cb(Date.now()), 16),
+    cancel: (h) => clearTimeout(h)
+  };
+}
+var Motion = class {
+  o;
+  entries = /* @__PURE__ */ new Map();
+  /** Tracks whose picture can still change. Everything else costs nothing per frame. */
+  active = /* @__PURE__ */ new Set();
+  listeners = /* @__PURE__ */ new Set();
+  offsets = [];
+  offset = 0;
+  handle = null;
+  lastFrameAt = Number.NEGATIVE_INFINITY;
+  constructor(options) {
+    this.o = resolve(options);
+  }
+  get size() {
+    return this.entries.size;
+  }
+  offsetMs() {
+    return this.offset;
+  }
+  // ── time ────────────────────────────────────────────────────────────────
+  /** Browser clock + learned offset = the server's clock. */
+  serverNow(at) {
+    return (at ?? this.o.clock()) + this.offset;
+  }
+  /**
+   * `serverTime - browserNow` is the true offset MINUS the network delay, so the
+   * largest recent value is the one with the least delay, i.e. the best estimate.
+   */
+  observe(serverTime) {
+    if (!Number.isFinite(serverTime)) return;
+    this.offsets.push(serverTime - this.o.clock());
+    if (this.offsets.length > OFFSET_WINDOW) this.offsets.shift();
+    this.offset = Math.max(...this.offsets);
+  }
+  cap(e) {
+    const m = this.o.maxExtrapolateMs;
+    return e.surface ? m.surface : m.air;
+  }
+  // ── model ───────────────────────────────────────────────────────────────
+  posAt(e, s) {
+    const cap = this.cap(e);
+    let elapsed = Math.min(Math.max(0, s - e.fixAt), cap);
+    if (e.frozen !== null) elapsed = Math.min(elapsed, e.frozen);
+    if (!this.o.extrapolate || e.course === null || e.speedMs <= 0) {
+      return { lat: e.fixLat, lon: e.fixLon, extrapolating: false };
+    }
+    const p = move(e.fixLat, e.fixLon, e.course, e.speedMs * elapsed / 1e3);
+    return { ...p, extrapolating: e.frozen === null && elapsed < cap };
+  }
+  sampleAt(e, s) {
+    const p = this.posAt(e, s);
+    const rest = 1 - smoothstep((s - e.blendStart) / this.o.blendMs);
+    let headingDeg = null;
+    if (e.hdgTo !== null) {
+      const from = e.hdgFrom ?? e.hdgTo;
+      const left = 1 - smoothstep((s - e.hdgStart) / this.o.headingSmoothMs);
+      headingDeg = norm360(e.hdgTo + wrapDeg(from - e.hdgTo) * left);
+    }
+    let altitudeFt = null;
+    if (e.altTo !== null) {
+      const k = smoothstep((s - e.altStart) / this.o.blendMs);
+      altitudeFt = e.altFrom === null ? e.altTo : e.altFrom + (e.altTo - e.altFrom) * k;
+    }
+    return {
+      lat: p.lat + e.errLat * rest,
+      lon: p.lon + e.errLon * rest,
+      headingDeg,
+      altitudeFt,
+      moving: e.speedMs > 0,
+      extrapolating: p.extrapolating
+    };
+  }
+  // ── input ───────────────────────────────────────────────────────────────
+  update(t, meta) {
+    if (meta?.serverTime !== void 0) this.observe(meta.serverTime);
+    if (t.lat == null || t.lon == null || !Number.isFinite(t.lat) || !Number.isFinite(t.lon)) {
+      this.remove(t.trackId);
+      return;
+    }
+    const s = this.serverNow();
+    const e = this.entries.get(t.trackId);
+    if (!e) {
+      this.create(t, s);
+      return;
+    }
+    this.refresh(e, t, s);
+  }
+  moving(t, course) {
+    const kt = t.groundSpeedKt;
+    return course !== null && kt != null && Number.isFinite(kt) && kt >= this.o.minMovingKt && kt <= MAX_PLAUSIBLE_KT;
+  }
+  create(t, s) {
+    const course = validHeading(t.headingDeg);
+    const moving = this.moving(t, course);
+    const e = {
+      id: t.trackId,
+      fixLat: t.lat,
+      fixLon: t.lon,
+      fixAt: t.lastSeenAt,
+      speedMs: moving ? t.groundSpeedKt * KT_TO_MS : 0,
+      course,
+      surface: this.o.isSurface(t),
+      frozen: null,
+      errLat: 0,
+      errLon: 0,
+      blendStart: s,
+      hdgFrom: course,
+      hdgTo: course,
+      hdgStart: s,
+      altFrom: null,
+      altTo: t.altitudeFt,
+      altStart: s,
+      settleAt: 0,
+      emitted: null
+    };
+    if (t.status === "lost") e.frozen = this.frozenAt(e, s);
+    this.entries.set(e.id, e);
+    this.settle(e);
+    this.active.add(e.id);
+    this.ensureLoop();
+  }
+  frozenAt(e, s) {
+    return Math.min(Math.max(0, s - e.fixAt), this.cap(e));
+  }
+  refresh(e, t, s) {
+    e.surface = this.o.isSurface(t);
+    if (t.status === "lost") e.frozen ??= this.frozenAt(e, s);
+    else e.frozen = null;
+    const lat = t.lat;
+    const lon = t.lon;
+    const older = t.lastSeenAt < e.fixAt;
+    const same = t.lastSeenAt === e.fixAt && lat === e.fixLat && lon === e.fixLon;
+    if (older || same) {
+      this.settle(e);
+      this.touch(e);
+      return;
+    }
+    const shown = this.sampleAt(e, s);
+    const course = validHeading(t.headingDeg) ?? e.course;
+    const moving = this.moving(t, course);
+    e.fixLat = lat;
+    e.fixLon = lon;
+    e.fixAt = t.lastSeenAt;
+    e.speedMs = moving ? t.groundSpeedKt * KT_TO_MS : 0;
+    e.course = course;
+    const predicted = this.posAt(e, s);
+    const jump = distanceM(shown.lat, shown.lon, predicted.lat, predicted.lon);
+    const snap = jump > this.o.snapDistanceM;
+    e.errLat = snap ? 0 : shown.lat - predicted.lat;
+    e.errLon = snap ? 0 : shown.lon - predicted.lon;
+    e.blendStart = s;
+    e.hdgFrom = snap ? course : shown.headingDeg ?? course;
+    e.hdgTo = course;
+    e.hdgStart = s;
+    e.altFrom = snap ? t.altitudeFt : shown.altitudeFt;
+    e.altTo = t.altitudeFt;
+    e.altStart = s;
+    this.settle(e);
+    this.touch(e);
+  }
+  /** The server time after which nothing about this track changes on its own. */
+  settle(e) {
+    const ends = [e.blendStart + this.o.blendMs, e.hdgStart + this.o.headingSmoothMs, e.altStart + this.o.blendMs];
+    if (this.o.extrapolate && e.speedMs > 0 && e.frozen === null) ends.push(e.fixAt + this.cap(e));
+    e.settleAt = Math.max(...ends);
+  }
+  touch(e) {
+    this.active.add(e.id);
+    this.ensureLoop();
+  }
+  remove(trackId) {
+    this.entries.delete(trackId);
+    this.active.delete(trackId);
+  }
+  clear() {
+    this.entries.clear();
+    this.active.clear();
+  }
+  // ── output ──────────────────────────────────────────────────────────────
+  sample(trackId, at) {
+    const e = this.entries.get(trackId);
+    return e ? this.sampleAt(e, this.serverNow(at)) : void 0;
+  }
+  differs(a, b) {
+    if (a === null || a.moving !== b.moving || a.extrapolating !== b.extrapolating) return true;
+    if (distanceM(a.lat, a.lon, b.lat, b.lon) > this.o.epsilonM) return true;
+    return headingChanged(a.headingDeg, b.headingDeg) || altitudeChanged(a.altitudeFt, b.altitudeFt);
+  }
+  tick(at) {
+    const s = this.serverNow(at);
+    const changed = /* @__PURE__ */ new Map();
+    for (const id of [...this.active]) {
+      const e = this.entries.get(id);
+      if (!e) {
+        this.active.delete(id);
+        continue;
+      }
+      const sample = this.sampleAt(e, s);
+      if (this.differs(e.emitted, sample)) {
+        e.emitted = sample;
+        changed.set(id, sample);
+      }
+      if (s >= e.settleAt) this.active.delete(id);
+    }
+    return changed;
+  }
+  // ── frame loop ──────────────────────────────────────────────────────────
+  start(onFrame) {
+    this.listeners.add(onFrame);
+    this.ensureLoop();
+    return () => {
+      this.listeners.delete(onFrame);
+      if (this.listeners.size === 0) this.cancelLoop();
+    };
+  }
+  ensureLoop() {
+    if (this.handle !== null || this.listeners.size === 0 || this.active.size === 0) return;
+    const scheduler = this.o.scheduler ?? (this.o.scheduler = defaultScheduler());
+    this.handle = scheduler.request((ts) => this.frame(ts));
+  }
+  cancelLoop() {
+    if (this.handle === null) return;
+    (this.o.scheduler ?? defaultScheduler()).cancel(this.handle);
+    this.handle = null;
+  }
+  frame(ts) {
+    this.handle = null;
+    if (this.listeners.size === 0) return;
+    if (ts - this.lastFrameAt >= 1e3 / this.o.frameHz - 1) {
+      this.lastFrameAt = ts;
+      const changed = this.tick();
+      if (changed.size > 0) {
+        const frame = { at: this.serverNow(), changed };
+        for (const fn of [...this.listeners]) fn(frame);
+      }
+    }
+    this.ensureLoop();
+  }
+};
+function createTrackMotion(options = {}) {
+  return new Motion(options);
+}
 export {
   AeroReplayClient,
   AeroSwarm,
   AeroWsClient,
+  LABEL_COLORS,
   TrackCache,
   clamp,
+  createTrackMotion,
+  getLabelCategory,
   haversineKm,
   isInsideBbox,
   isRenderableTrack2 as isRenderableTrack,
-  toCurrentTrack
+  toCurrentTrack,
+  withLabel
 };
 //# sourceMappingURL=index.js.map