@aeroswarm/client 0.1.12 → 0.1.13

package/dist/react/index.js

@@ -144,12 +144,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);
@@ -571,15 +572,15 @@ var AeroSwarm = class _AeroSwarm {
             this._status = s;
             callbacks.onStatusChange?.(s);
           },
-          onSnapshot: (tracks) => {
+          onSnapshot: (tracks, meta) => {
             const labeled = this.cache.applySnapshot(tracks);
             this._lastUpdateAt = Date.now();
-            callbacks.onSnapshot?.(labeled);
+            callbacks.onSnapshot?.(labeled, meta);
           },
-          onTrackUpdate: (track) => {
+          onTrackUpdate: (track, meta) => {
             const labeled = this.cache.applyUpdate(track);
             this._lastUpdateAt = Date.now();
-            callbacks.onTrackUpdate?.(labeled);
+            callbacks.onTrackUpdate?.(labeled, meta);
           },
           onTrackRemoved: (ev) => {
             this.cache.applyRemoved(ev);
@@ -604,7 +605,7 @@ var AeroSwarm = class _AeroSwarm {
     reconnect: () => this.wsClient.reconnect(),
     stream: (opts) => {
       const queue = [];
-      let resolve = null;
+      let resolve2 = null;
       let done = false;
       this.wsClient.connect({ encoding: "json", ...opts }, {
         onSnapshot: (tracks) => {
@@ -612,9 +613,9 @@ var AeroSwarm = class _AeroSwarm {
         },
         onTrackUpdate: (raw) => {
           const t = this.cache.applyUpdate(raw);
-          if (resolve) {
-            resolve({ value: t, done: false });
-            resolve = null;
+          if (resolve2) {
+            resolve2({ value: t, done: false });
+            resolve2 = null;
           } else queue.push(t);
         },
         onStatusChange: (s) => {
@@ -627,7 +628,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 () => {
@@ -820,8 +821,331 @@ function AeroSwarmProvider({
   return /* @__PURE__ */ jsx(QueryClientProvider, { client: qc, children: /* @__PURE__ */ jsx(AeroSwarmContext.Provider, { value: { client }, children }) });
 }
 
+// src/react/hooks/use-track-motion.ts
+import { useEffect, useMemo as useMemo2, useRef } from "react";
+
+// 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);
+}
+
+// src/react/hooks/use-track-motion.ts
+function useTrackMotion(options) {
+  const { onFrame, ...motionOptions } = options;
+  const onFrameRef = useRef(onFrame);
+  onFrameRef.current = onFrame;
+  const motion = useMemo2(() => createTrackMotion(motionOptions), []);
+  useEffect(() => {
+    const stop = motion.start((frame) => onFrameRef.current(frame));
+    return () => {
+      stop();
+      motion.clear();
+    };
+  }, [motion]);
+  return motion;
+}
+
 // src/react/hooks/use-track-history.ts
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect as useEffect2, useRef as useRef2 } from "react";
 var DR_MIN_SPEED_KT = 10;
 var MAX_SPEED_KT = 1200;
 var GAP_RESET_MS = 3e4;
@@ -841,22 +1165,22 @@ function useTrackHistory(options) {
     maxJumpDeg = 5,
     onFrame
   } = options;
-  const currentPositions = useRef(/* @__PURE__ */ new Map());
-  const lastActualPos = useRef(/* @__PURE__ */ new Map());
-  const history = useRef(/* @__PURE__ */ new Map());
-  const lastSeen = useRef(/* @__PURE__ */ new Map());
-  const lastUpdPerf = useRef(/* @__PURE__ */ new Map());
-  const interp = useRef(/* @__PURE__ */ new Map());
-  const velocity = useRef(/* @__PURE__ */ new Map());
-  const drState = useRef(/* @__PURE__ */ new Map());
-  const rafRef = useRef(null);
-  const onFrameRef = useRef(onFrame);
+  const currentPositions = useRef2(/* @__PURE__ */ new Map());
+  const lastActualPos = useRef2(/* @__PURE__ */ new Map());
+  const history = useRef2(/* @__PURE__ */ new Map());
+  const lastSeen = useRef2(/* @__PURE__ */ new Map());
+  const lastUpdPerf = useRef2(/* @__PURE__ */ new Map());
+  const interp = useRef2(/* @__PURE__ */ new Map());
+  const velocity = useRef2(/* @__PURE__ */ new Map());
+  const drState = useRef2(/* @__PURE__ */ new Map());
+  const rafRef = useRef2(null);
+  const onFrameRef = useRef2(onFrame);
   onFrameRef.current = onFrame;
-  const maxHistoryPointsRef = useRef(maxHistoryPoints);
+  const maxHistoryPointsRef = useRef2(maxHistoryPoints);
   maxHistoryPointsRef.current = maxHistoryPoints;
-  const minDeltaDegRef = useRef(minDeltaDeg);
+  const minDeltaDegRef = useRef2(minDeltaDeg);
   minDeltaDegRef.current = minDeltaDeg;
-  const maxJumpDegRef = useRef(maxJumpDeg);
+  const maxJumpDegRef = useRef2(maxJumpDeg);
   maxJumpDegRef.current = maxJumpDeg;
   function emitFrame() {
     onFrameRef.current({
@@ -1019,7 +1343,7 @@ function useTrackHistory(options) {
     drState.current.delete(trackId);
     emitFrame();
   }, []);
-  useEffect(() => {
+  useEffect2(() => {
     return () => {
       if (rafRef.current !== null) {
         cancelAnimationFrame(rafRef.current);
@@ -1034,7 +1358,7 @@ function useTrackHistory(options) {
 }
 
 // src/react/hooks/index.ts
-import { useCallback as useCallback2, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2 } from "react";
+import { useCallback as useCallback2, useEffect as useEffect3, useMemo as useMemo3, useRef as useRef3 } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { useShallow } from "zustand/react/shallow";
 
@@ -1134,7 +1458,7 @@ function useAeroTracks(opts = {}) {
   const isDegraded = useTrackStore(selectIsDegraded);
   const lastUpdateAt = useTrackStore(selectLastUpdateAt);
   const error = useTrackStore(selectError);
-  const unsubRef = useRef2(null);
+  const unsubRef = useRef3(null);
   const { isLoading } = useQuery({
     queryKey: ["aero-snapshot", opts.bbox?.join(","), opts.source, opts.minConfidence],
     enabled: opts.enabled !== false,
@@ -1148,7 +1472,7 @@ function useAeroTracks(opts = {}) {
       return result;
     }
   });
-  useEffect2(() => {
+  useEffect3(() => {
     if (opts.enabled === false) return;
     const actions = useTrackStore.getState();
     unsubRef.current = client.tracks.subscribe(
@@ -1190,7 +1514,7 @@ function useAeroTracks(opts = {}) {
 }
 var useTracks = useAeroTracks;
 function useAeroTrack(trackId) {
-  const track = useTrackStore(useMemo2(() => selectTrack(trackId), [trackId]));
+  const track = useTrackStore(useMemo3(() => selectTrack(trackId), [trackId]));
   return { track };
 }
 function useAeroSnapshot(opts = {}) {
@@ -1283,6 +1607,7 @@ export {
   useSourceHealth,
   useTrackCount,
   useTrackHistory,
+  useTrackMotion,
   useTrackStore,
   useTracks,
   useWebhooks