@aeroswarm/client 0.1.12 → 0.1.13

package/README.md

@@ -449,7 +449,41 @@ 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` |
 
-### `useTrackHistory` — smooth map animation
+### `useTrackMotion` / `createTrackMotion` — smooth live tracks
+
+Feeds update a track once a second (MLAT, ADS-B) or once per antenna sweep (radar, ~7.5 s). Drawn as they arrive, icons jump. `createTrackMotion` (no React needed) shows where the aircraft *probably is right now* and eases corrections in, like a flight tracker:
+
+```ts
+import { createTrackMotion } from "@aeroswarm/client";
+
+const motion = createTrackMotion();                     // all options optional
+
+client.tracks.subscribe(opts, {
+  onSnapshot: (tracks, meta) => tracks.forEach((t) => motion.update(t, meta)),
+  onTrackUpdate: (t, meta) => motion.update(t, meta),   // meta.serverTime keeps the clocks aligned
+  onTrackRemoved: ({ trackId }) => motion.remove(trackId),
+});
+
+const stop = motion.start(({ changed }) => {            // ~30 frames/s, only tracks that moved
+  for (const [id, s] of changed) layer.put(id, s.lat, s.lon, s.headingDeg);
+});
+```
+
+React: `const motion = useTrackMotion({ onFrame })`, then call `motion.update(...)` from the subscription. Nothing here renders React.
+
+What it does:
+
+| | |
+|---|---|
+| **Dead reckoning** | From the last fix, speed and heading carry the position forward, up to `maxExtrapolateMs` (20 s in the air, 8 s on the surface). `lost` tracks freeze. |
+| **Eased corrections** | A new fix does not snap the icon. The gap between where it was shown and where the fix says it should be becomes an offset that fades out (smoothstep over `blendMs`, 1.5 s). The icon keeps moving at its own speed meanwhile, so there is no stop-and-go at every update. A correction larger than `snapDistanceM` (5 km) is a glitch and jumps. |
+| **Heading** | Eases along the shortest arc (`headingSmoothMs`, 0.8 s); keeps the last heading when the track stops. |
+| **Server clock** | `lastSeenAt` is the server's clock. `meta.serverTime` of each message lets the engine learn the offset to the browser clock (the estimate with the least network delay wins), so a wrong browser clock does not stretch or shrink the prediction. |
+| **Cheap frames** | Tracks that stand still, or whose picture changed by less than `epsilonM` (0.5 m) / 0.5°, are not reported; no timer runs while nothing moves; `frameHz` caps the rate (30). |
+
+Options (`MotionOptions`): `blendMs`, `headingSmoothMs`, `maxExtrapolateMs`, `minMovingKt` (5), `snapDistanceM`, `frameHz`, `epsilonM`, `extrapolate` (`false` shows raw positions, for comparing sources), `isSurface`, `clock` (inject the replay clock to play back at another speed), `scheduler` (tests). `motion.sample(id)` gives the shown position at any time without touching frame state, e.g. to attach a trail's head to the icon.
+
+### `useTrackHistory` — smooth map animation (deprecated: use `useTrackMotion`)
 
 Maintains per-track position interpolation (tweening), dead-reckoning between updates, and bounded trail history, emitting animation frames outside React render: