@aeroswarm/live-server 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# @aeroswarm/live-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The live-picture runtime AeroSwarm's `client-service` uses, packaged so a backend can serve the
+**same live WebSocket** (`/ws/tracks/live`) without running AeroSwarm's services. `@aeroswarm/client`
+connects to it unchanged.
+
+| Piece | What it does |
+|---|---|
+| `createTrackState` | Current tracks: `active → stale → lost → removed`, de-dupe by Mode-S address, flight-plan attachment, filtered snapshots |
+| `createFlightPlanStore` | AFTN messages folded into flight plans; correlation to live tracks (Mode-S, then callsign; the leg in progress wins) |
+| `createMovementDetector` | Takeoff / landing detection from consecutive track samples |
+| `createLiveServer` | WebSocket handlers speaking the AeroSwarm envelope protocol |
+
+No I/O: no database, Kafka, Redis or auth. The host injects `authenticate` and persists from the
+events these classes emit. Depends only on `@aeroswarm/core` (bundled) and `zod`.
+
+## Wiring
+
+```ts
+import { createFlightPlanStore, createTrackState, createLiveServer, createMovementDetector } from "@aeroswarm/live-server";
+
+const plans = createFlightPlanStore();
+const state = createTrackState({ attachFlightPlan: plans.attach });
+plans.on("changed", (plan) => {
+  state.refreshFlightPlans((t) => plans.matches(plan, t)); // push the plan to tracks already on screen
+  persist(plan);                                           // host's job
+});
+state.startSweep();   // recomputes stale/lost every 5 s; required, or tracks never go lost
+plans.startSweep();
+
+const live = createLiveServer({
+  state,
+  authenticate: async (token) => (await verify(token)) ? { airportId: "WARR" } : null,
+});
+
+// feeds (see @aeroswarm/ingest)
+trackSource.start((ev) => { if (ev.kind === "track") state.ingest(ev.event as FusedTrackEvent); });
+aftnSource.start((ev)  => { if (ev.kind === "flightplan") plans.apply(ev.event); });
+
+// movements
+const movements = createMovementDetector();
+state.on("update", (t) => {
+  const m = movements.update({ trackId: t.trackId, icao24: t.icao24, callsign: t.callsign, airportId: t.airportId,
+    at: t.lastSeenAt, lat: t.lat!, lon: t.lon!, altitudeFt: t.altitudeFt, groundSpeedKt: t.groundSpeedKt });
+  if (m) saveMovement(m);
+});
+state.on("removed", ({ trackId }) => movements.forget(trackId));
+```
+
+### Bun
+
+```ts
+Bun.serve({
+  fetch(req, srv) {
+    const url = new URL(req.url);
+    if (url.pathname === "/ws/tracks/live")
+      return srv.upgrade(req, { data: { token: url.searchParams.get("token") } }) ? undefined : new Response("upgrade failed", { status: 400 });
+    // ...
+  },
+  websocket: {
+    open: (ws) => live.handlers.open(ws, { token: ws.data.token }),
+    message: (ws, raw) => live.handlers.message(ws, raw),
+    close: (ws) => live.handlers.close(ws),
+  },
+});
+```
+
+### `ws` library
+
+```ts
+wss.on("connection", (ws, req) => {
+  void live.handlers.open(ws, { token: new URL(req.url!, "http://x").searchParams.get("token") });
+  ws.on("message", (m) => live.handlers.message(ws, m.toString()));
+  ws.on("close", () => live.handlers.close(ws));
+});
+```
+
+## Protocol
+
+JSON envelopes `{ type, seq, serverTime, payload }`, `seq` strictly increasing across the server.
+
+| Server sends | Payload |
+|---|---|
+| `snapshot` | `{ tracks: CurrentTrack[] }`, on `subscribe` and `update-filter` |
+| `track.updated` | `{ track }`, rate-limited per client per track (`maxUpdateHz`); status and flight-plan changes are never throttled |
+| `track.removed` | `{ trackId, reason }`, reason is `dropped`, `superseded`, `lost`, `evicted` (over `maxTracks`) or `filtered` (left the client's filter) |
+| `source.status` / `stream.degraded` | via `live.sourceStatus()` / `live.degraded()` |
+| `stream.heartbeat` | every `heartbeatMs` (default 15 s) and once on open |
+| `stream.error` | `{ code, message, recoverable: true }` for `BAD_JSON`, `BAD_SUBSCRIBE`, `BAD_FILTER` |
+
+Client sends `subscribe` (`bbox`, `airportId`, `minConfidence`, `maxTracks`, `maxUpdateHz`, …) and
+`update-filter`. Always JSON; `encoding: "msgpack"` is accepted but ignored.
+
+Close codes: `4001` no token, `4003` rejected by `authenticate`, `1001` server stopping.
+Messages that arrive before `authenticate` resolves are queued, not dropped.
+
+### Airport scoping
+
+`authenticate` returning `{ airportId }` pins the connection to that airport, whatever the client
+subscribes with (a sensor token). Return `{}` for a viewer token that may ask for any airport.
+
+## Status semantics
+
+`toCurrentTrack` computes `status` once. `TrackState.sweep()` recomputes it from `lastSeenAt` and
+emits only when it actually changes, so a quiet stretch does not spam clients. Defaults: stale after
+15 s, lost after 90 s, removed after 30 min (`staleAfterMs`, `lostAfterMs`, `removeAfterMs`).
+
+## Scaling
+
+State is in-process memory: run one instance, or put a shared fan-out in front.
+
+## Develop
+
+```
+pnpm --filter @aeroswarm/live-server test
+pnpm --filter @aeroswarm/live-server build
+```
+
+`test/client-integration.test.ts` runs the real `AeroWsClient` / `TrackCache` from
+`@aeroswarm/client` against a live server over a socket, including `reconnect()`.

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+import { CurrentTrack, FusedTrackEvent, FlightPlan, FlightPlanEvent } from '@aeroswarm/core/types';
+
+/** Minimal socket surface. Satisfied by Bun's `ServerWebSocket` and the `ws` library. */
+interface LiveSocket {
+    send(data: string): unknown;
+    close(code?: number, reason?: string): unknown;
+    /** Optional; used for backpressure when present. */
+    getBufferedAmount?(): number;
+}
+interface Logger {
+    info(obj: unknown, msg?: string): void;
+    warn(obj: unknown, msg?: string): void;
+    error(obj: unknown, msg?: string): void;
+}
+type Bbox = [number, number, number, number];
+interface TrackFilter {
+    airportId?: string;
+    bbox?: Bbox;
+    minConfidence?: number;
+    maxTracks?: number;
+}
+type RemoveReason = "dropped" | "superseded" | "lost" | "evicted" | "filtered";
+interface UpdateInfo {
+    /** Bypass per-client rate limiting (status change, flight-plan change). */
+    force: boolean;
+}
+type TrackListener = (track: CurrentTrack, info: UpdateInfo) => void;
+type RemovedListener = (ev: {
+    trackId: string;
+    reason: RemoveReason;
+}) => void;
+
+interface TrackStateOptions {
+    /** Default STALE_AFTER_MS (15 s). */
+    staleAfterMs?: number;
+    /** Default LOST_AFTER_MS (90 s). */
+    lostAfterMs?: number;
+    /** Tracks unseen this long are removed. 0 disables. Default 30 min. */
+    removeAfterMs?: number;
+    /** Drop tracks outside this box unless heading into it within the lookahead. */
+    interestBbox?: Bbox;
+    /** Minutes. Default 90. */
+    interestLookaheadMin?: number;
+    /** Clock, for tests. Default Date.now. */
+    now?: () => number;
+    /** Attach flight-plan data, e.g. `flightPlanStore.attach`. */
+    attachFlightPlan?: (track: CurrentTrack) => CurrentTrack;
+}
+/** Live picture of all tracks: lifecycle (active, stale, lost, removed),
+ *  de-duplication by Mode-S address, flight-plan attachment. No I/O. */
+declare class TrackState {
+    private readonly opts;
+    private readonly tracks;
+    private readonly byIcao24;
+    private readonly onUpdate;
+    private readonly onRemoved;
+    private readonly staleAfterMs;
+    private readonly lostAfterMs;
+    private readonly removeAfterMs;
+    private sweepTimer;
+    private readonly now;
+    constructor(opts?: TrackStateOptions);
+    private statusFor;
+    on(event: "update", fn: TrackListener): () => void;
+    on(event: "removed", fn: RemovedListener): () => void;
+    get size(): number;
+    get(trackId: string): CurrentTrack | undefined;
+    values(): IterableIterator<CurrentTrack>;
+    /** Apply one fused event. Returns the resulting track, or null when the event
+     *  removed a track or was ignored. */
+    ingest(fused: FusedTrackEvent): CurrentTrack | null;
+    /** Remove a track (no-op if unknown). */
+    drop(trackId: string, reason?: RemoveReason): void;
+    /** Recompute `status` from `lastSeenAt` and remove long-gone tracks.
+     *  Emits only on a real status change. Call every few seconds. */
+    sweep(now?: number): void;
+    /** Re-attach flight plans, emitting only for tracks whose plan data changed.
+     *  Call when a plan changes so clients see it before the next radar update. */
+    refreshFlightPlans(match?: (track: CurrentTrack) => boolean): void;
+    snapshot(filter?: TrackFilter): CurrentTrack[];
+    /** Run `sweep` on an interval. Idempotent. */
+    startSweep(intervalMs?: number): void;
+    stopSweep(): void;
+    private remove;
+    private emitUpdate;
+    private inInterestZone;
+}
+declare function createTrackState(opts?: TrackStateOptions): TrackState;
+
+interface FlightPlanStoreOptions {
+    /** Plans untouched this long are dropped from memory. Default 48 h. */
+    ttlMs?: number;
+}
+interface FlightPlanFilter {
+    airportId?: string;
+    status?: string;
+    callsign?: string;
+    limit?: number;
+}
+type Listener<T> = (value: T) => void;
+/** Flight plans folded from AFTN messages, indexed for correlation with live
+ *  tracks (Mode-S address first, then callsign). No I/O: the host persists via
+ *  the `changed` event and restores with `load`. */
+declare class FlightPlanStore {
+    private readonly plans;
+    private readonly byCallsign;
+    private readonly byIcao24;
+    private readonly onChanged;
+    private readonly onExpired;
+    private readonly ttlMs;
+    private sweepTimer;
+    constructor(opts?: FlightPlanStoreOptions);
+    /** `changed`: a plan was created or updated. `expired`: a plan id left memory. */
+    on(event: "changed", fn: Listener<FlightPlan>): () => void;
+    on(event: "expired", fn: Listener<string>): () => void;
+    get size(): number;
+    get(id: string): FlightPlan | undefined;
+    /** Fold one AFTN message into its flight. Returns the updated plan, or null if ignored. */
+    apply(ev: FlightPlanEvent): FlightPlan | null;
+    /** Restore plans (e.g. from a database after a restart). Does not emit `changed`. */
+    load(plans: FlightPlan[], now?: number): number;
+    /** Best plan for a live track. Every plan sharing the Mode-S address or
+     *  callsign is a candidate (an airframe flies several legs a day); the leg
+     *  in progress, or nearest in time, wins. Cancelled plans never match. */
+    find(track: Pick<CurrentTrack, "icao24" | "callsign">, now?: number): FlightPlan | undefined;
+    /** Track with its flight-plan summary attached; unchanged when none matches.
+     *  An arrow property so it can be passed unbound, e.g. `{ attachFlightPlan: store.attach }`. */
+    readonly attach: (track: CurrentTrack) => CurrentTrack;
+    /** True if `plan` could correlate with `track`. Pair with `TrackState.refreshFlightPlans`. */
+    matches(plan: FlightPlan, track: Pick<CurrentTrack, "icao24" | "callsign">): boolean;
+    list(filter?: FlightPlanFilter): FlightPlan[];
+    /** Drop plans past the TTL; returns their ids. */
+    sweep(now?: number): string[];
+    startSweep(intervalMs?: number): void;
+    stopSweep(): void;
+    private index;
+    private unindex;
+}
+declare function createFlightPlanStore(opts?: FlightPlanStoreOptions): FlightPlanStore;
+
+/**
+ * Takeoff / landing detection from consecutive track states.
+ *
+ * Pure, dependency-free state machine. One detector instance tracks many
+ * targets. Copied from process-service so backends running without
+ * AeroSwarm's services get identical detection.
+ *
+ * Heuristics (dual-threshold hysteresis so noisy altitude/on-ground
+ * flags don't double-count):
+ *   ground → airborne  at ≥ TAKEOFF_MIN_GS_KT and (onGround=false or
+ *                      alt > AIRBORNE_ALT_FT)          ⇒ takeoff
+ *   airborne → ground  at ≤ LANDING_MAX_GS_KT and (onGround=true or
+ *                      alt < GROUND_ALT_FT)            ⇒ landing
+ */
+type MovementType = "takeoff" | "landing";
+interface MovementEvent {
+    trackId: string;
+    icao24: string | null;
+    callsign: string | null;
+    airportId?: string;
+    type: MovementType;
+    /** Unix epoch ms of the transition */
+    at: number;
+    lat: number;
+    lon: number;
+}
+interface MovementSample {
+    trackId: string;
+    icao24?: string | null;
+    callsign?: string | null;
+    airportId?: string;
+    at: number;
+    lat: number;
+    lon: number;
+    altitudeFt?: number | null;
+    groundSpeedKt?: number | null;
+    onGround?: boolean;
+}
+declare class MovementDetector {
+    private phases;
+    /** Feed one track state; returns a movement event on a transition. */
+    update(s: MovementSample): MovementEvent | null;
+    /** Forget one track (call when its track is removed). */
+    forget(trackId: string): void;
+    /** Forget tracks not updated within maxAgeMs (call periodically). */
+    sweep(maxAgeMs: number, now?: number): void;
+    get trackedCount(): number;
+    private makeEvent;
+}
+declare function createMovementDetector(): MovementDetector;
+
+/** Result of `authenticate`. `airportId` pins the connection to that airport
+ *  (a sensor token); leave it undefined for viewer tokens that may request any. */
+interface LiveAuth {
+    airportId?: string;
+}
+interface LiveServerOptions {
+    state: TrackState;
+    /** Return null to reject. A missing token is rejected (4001) before this is called. */
+    authenticate: (token: string) => Promise<LiveAuth | null> | LiveAuth | null;
+    /** Per-client, per-track push rate when the client does not ask for one. Default 10. */
+    defaultUpdateHz?: number;
+    /** Default 15 000. */
+    heartbeatMs?: number;
+    /** Skip non-forced deltas for sockets buffering more than this. Default 1 MiB. */
+    maxBufferedBytes?: number;
+    logger?: Logger;
+}
+interface LiveOpenContext {
+    /** Value of the `token` query parameter, read by the host at upgrade time. */
+    token: string | null;
+}
+interface LiveServerStats {
+    clients: number;
+    subscribed: number;
+    messagesSent: number;
+    deltasSkipped: number;
+}
+type LiveMessage = string | ArrayBuffer | Uint8Array;
+interface LiveServer {
+    handlers: {
+        open(ws: LiveSocket, ctx: LiveOpenContext): Promise<void>;
+        message(ws: LiveSocket, raw: LiveMessage): void;
+        close(ws: LiveSocket): void;
+    };
+    /** Tell clients a data source changed health. */
+    sourceStatus(sourceId: string, status: "healthy" | "degraded" | "offline"): void;
+    /** Tell clients the stream is degraded (e.g. a feed went silent). */
+    degraded(reason: string, sourceId?: string): void;
+    stats(): LiveServerStats;
+    /** Stop timers and close every socket. */
+    stop(): void;
+}
+declare function createLiveServer(opts: LiveServerOptions): LiveServer;
+
+export { type Bbox, type FlightPlanFilter, FlightPlanStore, type FlightPlanStoreOptions, type LiveAuth, type LiveMessage, type LiveOpenContext, type LiveServer, type LiveServerOptions, type LiveServerStats, type LiveSocket, type Logger, MovementDetector, type MovementEvent, type MovementSample, type MovementType, type RemoveReason, type RemovedListener, type TrackFilter, type TrackListener, TrackState, type TrackStateOptions, type UpdateInfo, createFlightPlanStore, createLiveServer, createMovementDetector, createTrackState };

package/dist/index.js

@@ -0,0 +1,929 @@
+// ../core/dist/chunk-J2UTSYKD.js
+function toCurrentTrack(fused, staleAfterMs = 15e3, lostAfterMs = 9e4) {
+  const age = Date.now() - fused.updatedAt;
+  const status = age > lostAfterMs ? "lost" : age > staleAfterMs ? "stale" : "active";
+  const src = fused.sources.length > 1 ? "FUSED" : protocolToSource(fused.protocol);
+  const rawHeading = fused.velocity?.heading;
+  const headingDeg = rawHeading != null ? (rawHeading % 360 + 360) % 360 : null;
+  return {
+    trackId: fused.trackId,
+    source: src,
+    icao24: fused.identity.icao24 ?? null,
+    callsign: fused.identity.callsign ?? null,
+    squawk: fused.identity.squawk ?? null,
+    ...fused.identity.targetType !== void 0 && { targetType: fused.identity.targetType },
+    ...fused.identity.vehicleFleet !== void 0 && { vehicleFleet: fused.identity.vehicleFleet },
+    ...fused.airportId !== void 0 && { airportId: fused.airportId },
+    lat: fused.position?.lat ?? null,
+    lon: fused.position?.lon ?? null,
+    altitudeFt: fused.position?.alt ?? null,
+    groundSpeedKt: fused.velocity?.groundSpeed ?? null,
+    headingDeg,
+    verticalRateFpm: fused.velocity?.verticalRate ?? null,
+    confidence: fused.confidence.overall,
+    lastSeenAt: fused.updatedAt,
+    status
+  };
+}
+function protocolToSource(protocol) {
+  if (protocol === "asterix-cat010") return "ASTERIX_CAT010";
+  if (protocol === "asterix-cat011") return "ASTERIX_CAT011";
+  if (protocol === "asterix-cat020") return "ASTERIX_CAT020";
+  if (protocol === "asterix-cat021") return "ASTERIX_CAT021";
+  if (protocol === "asterix-cat048") return "ASTERIX_CAT048";
+  if (protocol === "asterix-cat062") return "ASTERIX_CAT062";
+  return "ADSB";
+}
+var STALE_AFTER_MS = 15e3;
+var LOST_AFTER_MS = 9e4;
+
+// src/types.ts
+var noopLogger = { info() {
+}, warn() {
+}, error() {
+} };
+function trackScore(t) {
+  return t.confidence * 1e13 + t.lastSeenAt;
+}
+function inBbox(t, bbox) {
+  if (!bbox) return true;
+  if (t.lat == null || t.lon == null) return true;
+  return t.lon >= bbox[0] && t.lat >= bbox[1] && t.lon <= bbox[2] && t.lat <= bbox[3];
+}
+function matchesFilter(t, f) {
+  if (f.airportId && t.airportId !== f.airportId) return false;
+  if (!inBbox(t, f.bbox)) return false;
+  if (f.minConfidence !== void 0 && t.confidence < f.minConfidence) return false;
+  return true;
+}
+
+// src/track-state.ts
+var DEFAULT_REMOVE_AFTER_MS = 18e5;
+function inside(lon, lat, b) {
+  return lon >= b[0] && lat >= b[1] && lon <= b[2] && lat <= b[3];
+}
+var TrackState = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+    this.staleAfterMs = opts.staleAfterMs ?? STALE_AFTER_MS;
+    this.lostAfterMs = opts.lostAfterMs ?? LOST_AFTER_MS;
+    this.removeAfterMs = opts.removeAfterMs ?? DEFAULT_REMOVE_AFTER_MS;
+    this.now = opts.now ?? Date.now;
+  }
+  opts;
+  tracks = /* @__PURE__ */ new Map();
+  byIcao24 = /* @__PURE__ */ new Map();
+  onUpdate = /* @__PURE__ */ new Set();
+  onRemoved = /* @__PURE__ */ new Set();
+  staleAfterMs;
+  lostAfterMs;
+  removeAfterMs;
+  sweepTimer = null;
+  now;
+  statusFor(age) {
+    return age > this.lostAfterMs ? "lost" : age > this.staleAfterMs ? "stale" : "active";
+  }
+  on(event, fn) {
+    const set = event === "update" ? this.onUpdate : this.onRemoved;
+    set.add(fn);
+    return () => {
+      set.delete(fn);
+    };
+  }
+  get size() {
+    return this.tracks.size;
+  }
+  get(trackId) {
+    return this.tracks.get(trackId);
+  }
+  values() {
+    return this.tracks.values();
+  }
+  /** Apply one fused event. Returns the resulting track, or null when the event
+   *  removed a track or was ignored. */
+  ingest(fused) {
+    if (fused.lifecycle === "dropped") {
+      this.remove(fused.trackId, "dropped");
+      return null;
+    }
+    if (this.opts.interestBbox && !this.inInterestZone(fused, this.opts.interestBbox)) return null;
+    const icao24 = fused.identity?.icao24;
+    if (icao24) {
+      const existing = this.byIcao24.get(icao24);
+      if (existing && existing !== fused.trackId && this.tracks.has(existing)) {
+        this.remove(existing, "superseded");
+      }
+      this.byIcao24.set(icao24, fused.trackId);
+    }
+    let current = toCurrentTrack(fused, this.staleAfterMs, this.lostAfterMs);
+    current = { ...current, status: this.statusFor(this.now() - current.lastSeenAt) };
+    if (this.opts.attachFlightPlan) current = this.opts.attachFlightPlan(current);
+    this.tracks.set(current.trackId, current);
+    this.emitUpdate(current, false);
+    return current;
+  }
+  /** Remove a track (no-op if unknown). */
+  drop(trackId, reason = "dropped") {
+    this.remove(trackId, reason);
+  }
+  /** Recompute `status` from `lastSeenAt` and remove long-gone tracks.
+   *  Emits only on a real status change. Call every few seconds. */
+  sweep(now = this.now()) {
+    for (const [trackId, track] of [...this.tracks]) {
+      const age = now - track.lastSeenAt;
+      if (this.removeAfterMs > 0 && age > this.removeAfterMs) {
+        this.remove(trackId, "lost");
+        continue;
+      }
+      const status = this.statusFor(age);
+      if (track.status === status) continue;
+      const updated = { ...track, status };
+      this.tracks.set(trackId, updated);
+      this.emitUpdate(updated, true);
+    }
+  }
+  /** Re-attach flight plans, emitting only for tracks whose plan data changed.
+   *  Call when a plan changes so clients see it before the next radar update. */
+  refreshFlightPlans(match) {
+    const attach = this.opts.attachFlightPlan;
+    if (!attach) return;
+    for (const [trackId, track] of [...this.tracks]) {
+      if (match && !match(track)) continue;
+      const next = attach(track);
+      if (JSON.stringify(next.flightPlan) === JSON.stringify(track.flightPlan)) continue;
+      this.tracks.set(trackId, next);
+      this.emitUpdate(next, true);
+    }
+  }
+  snapshot(filter = {}) {
+    let out = [...this.tracks.values()].filter((t) => matchesFilter(t, filter));
+    out.sort((a, b) => trackScore(b) - trackScore(a));
+    if (filter.maxTracks !== void 0) out = out.slice(0, filter.maxTracks);
+    return out;
+  }
+  /** Run `sweep` on an interval. Idempotent. */
+  startSweep(intervalMs = 5e3) {
+    if (this.sweepTimer) return;
+    this.sweepTimer = setInterval(() => this.sweep(), intervalMs);
+    this.sweepTimer.unref?.();
+  }
+  stopSweep() {
+    if (this.sweepTimer) clearInterval(this.sweepTimer);
+    this.sweepTimer = null;
+  }
+  remove(trackId, reason) {
+    const track = this.tracks.get(trackId);
+    if (!track) return;
+    this.tracks.delete(trackId);
+    if (track.icao24 && this.byIcao24.get(track.icao24) === trackId) this.byIcao24.delete(track.icao24);
+    for (const fn of this.onRemoved) fn({ trackId, reason });
+  }
+  emitUpdate(track, force) {
+    for (const fn of this.onUpdate) fn(track, { force });
+  }
+  inInterestZone(fused, bbox) {
+    const lat = fused.position?.lat;
+    const lon = fused.position?.lon;
+    if (lat == null || lon == null) return true;
+    if (inside(lon, lat, bbox)) return true;
+    const heading = fused.velocity?.heading;
+    const speedKt = fused.velocity?.groundSpeed;
+    if (heading == null || speedKt == null || speedKt < 10) return false;
+    const hours = (this.opts.interestLookaheadMin ?? 90) / 60;
+    const distDeg = speedKt * 1.852 * hours / 111.32;
+    const rad = heading * Math.PI / 180;
+    const projLat = lat + distDeg * Math.cos(rad);
+    const projLon = lon + distDeg * Math.sin(rad) / Math.cos(lat * Math.PI / 180);
+    return inside(projLon, projLat, bbox);
+  }
+};
+function createTrackState(opts) {
+  return new TrackState(opts);
+}
+
+// ../core/dist/chunk-3T3CHHEM.js
+var FLIGHT_PLAN_MATCH_WINDOW_MS = 36 * 36e5;
+function normalizeCallsign(cs) {
+  const v = cs?.trim().toUpperCase().replace(/\s+/g, "");
+  return v || void 0;
+}
+function dayKey(msg, receivedAt) {
+  if (msg.dof && /^\d{6}$/.test(msg.dof)) return `20${msg.dof}`;
+  const t = msg.eobtAt ?? msg.atdAt ?? msg.ataAt ?? receivedAt;
+  return new Date(t).toISOString().slice(0, 10).replace(/-/g, "");
+}
+function flightPlanId(msg, receivedAt) {
+  const callsign = normalizeCallsign(msg.callsign);
+  if (!callsign) return null;
+  return `${callsign}|${msg.adep ?? "-"}|${msg.ades ?? "-"}|${dayKey(msg, receivedAt)}`;
+}
+function pickMatchingPlan(candidates, msg, receivedAt) {
+  const ref = msg.eobtAt ?? msg.atdAt ?? msg.ataAt ?? receivedAt;
+  let best;
+  let bestDiff = Infinity;
+  for (const c of candidates) {
+    if (msg.adep && c.adep && msg.adep !== c.adep) continue;
+    if (msg.ades && c.ades && msg.ades !== c.ades) continue;
+    const planTime = c.atdAt ?? c.eobtAt ?? c.firstSeenAt;
+    const diff = Math.abs(planTime - ref);
+    if (diff <= FLIGHT_PLAN_MATCH_WINDOW_MS && diff < bestDiff) {
+      best = c;
+      bestDiff = diff;
+    }
+  }
+  return best;
+}
+function assignDefined(target, patch) {
+  for (const [k, v] of Object.entries(patch)) {
+    if (v !== void 0 && v !== null && v !== "") target[k] = v;
+  }
+}
+function eetMs(eet) {
+  if (!eet || !/^\d{4}$/.test(eet)) return void 0;
+  return (Number(eet.slice(0, 2)) * 60 + Number(eet.slice(2, 4))) * 6e4;
+}
+function applyFlightPlanEvent(prev, ev) {
+  const m = ev.message;
+  const callsign = normalizeCallsign(m.callsign);
+  if (!callsign) return null;
+  const id = prev?.id ?? flightPlanId(m, ev.receivedAt);
+  if (!id) return null;
+  const next = {
+    status: "filed",
+    airportId: ev.airportId,
+    firstSeenAt: ev.receivedAt,
+    ...prev,
+    id,
+    callsign,
+    other: { ...prev?.other ?? {} },
+    lastMessageType: m.type,
+    messageCount: (prev?.messageCount ?? 0) + 1,
+    updatedAt: ev.receivedAt
+  };
+  assignDefined(next, { icao24: m.icao24, registration: m.registration, dof: m.dof });
+  Object.assign(next.other, m.other);
+  if (!next.adep && m.adep) next.adep = m.adep;
+  if (!next.ades && m.ades) next.ades = m.ades;
+  switch (m.type) {
+    case "FPL":
+      assignDefined(next, {
+        aircraftType: m.aircraftType,
+        wake: m.wake,
+        flightRules: m.flightRules,
+        flightType: m.flightType,
+        adep: m.adep,
+        ades: m.ades,
+        alternates: m.alternates,
+        eobtAt: m.eobtAt,
+        eet: m.eet,
+        cruiseSpeed: m.cruiseSpeed,
+        cruiseLevel: m.cruiseLevel,
+        route: m.route,
+        equipment: m.equipment
+      });
+      if (prev?.status !== "departed" && prev?.status !== "arrived") next.status = "filed";
+      break;
+    case "CHG":
+      assignDefined(next, {
+        aircraftType: m.aircraftType,
+        wake: m.wake,
+        cruiseSpeed: m.cruiseSpeed,
+        cruiseLevel: m.cruiseLevel,
+        route: m.route
+      });
+      if (m.changes?.["13"]) assignDefined(next, { adep: m.adep, eobtAt: m.eobtAt });
+      if (m.changes?.["16"]) assignDefined(next, { ades: m.ades, eet: m.eet });
+      break;
+    case "DLA":
+      assignDefined(next, { eobtAt: m.eobtAt });
+      if (next.status === "filed" || next.status === "delayed") next.status = "delayed";
+      break;
+    case "DEP":
+      next.atdAt = m.atdAt ?? ev.receivedAt;
+      next.status = "departed";
+      break;
+    case "ARR":
+      next.ataAt = m.ataAt ?? ev.receivedAt;
+      next.status = "arrived";
+      break;
+    case "CNL":
+      next.status = "cancelled";
+      break;
+  }
+  const departure = next.atdAt ?? next.eobtAt;
+  const flightTime = eetMs(next.eet);
+  next.etaAt = next.ataAt ?? (departure !== void 0 && flightTime !== void 0 ? departure + flightTime : void 0);
+  return next;
+}
+function flightPhase(plan, airportId) {
+  const icao = airportId?.trim().toUpperCase();
+  if (icao && plan.ades === icao) return "ARRIVAL";
+  if (icao && plan.adep === icao) return "DEPARTURE";
+  return plan.adep || plan.ades ? "OVERFLIGHT" : "UNKNOWN";
+}
+function summarizeFlightPlan(plan, airportId) {
+  const summary = { id: plan.id, status: plan.status, phase: flightPhase(plan, airportId) };
+  assignDefined(summary, {
+    adep: plan.adep,
+    ades: plan.ades,
+    aircraftType: plan.aircraftType,
+    registration: plan.registration,
+    eobtAt: plan.eobtAt,
+    atdAt: plan.atdAt,
+    ataAt: plan.ataAt,
+    etaAt: plan.etaAt,
+    cruiseLevel: plan.cruiseLevel,
+    route: plan.route
+  });
+  return summary;
+}
+
+// src/flightplan-store.ts
+var FlightPlanStore = class {
+  plans = /* @__PURE__ */ new Map();
+  byCallsign = /* @__PURE__ */ new Map();
+  byIcao24 = /* @__PURE__ */ new Map();
+  onChanged = /* @__PURE__ */ new Set();
+  onExpired = /* @__PURE__ */ new Set();
+  ttlMs;
+  sweepTimer = null;
+  constructor(opts = {}) {
+    this.ttlMs = opts.ttlMs ?? 48 * 36e5;
+  }
+  on(event, fn) {
+    const set = event === "changed" ? this.onChanged : this.onExpired;
+    set.add(fn);
+    return () => {
+      set.delete(fn);
+    };
+  }
+  get size() {
+    return this.plans.size;
+  }
+  get(id) {
+    return this.plans.get(id);
+  }
+  /** Fold one AFTN message into its flight. Returns the updated plan, or null if ignored. */
+  apply(ev) {
+    const m = ev.message;
+    const callsign = normalizeCallsign(m.callsign);
+    if (!callsign) return null;
+    let prev;
+    if (m.type === "FPL") {
+      const id = flightPlanId(m, ev.receivedAt);
+      prev = id ? this.plans.get(id) : void 0;
+    } else {
+      const candidates = [...this.byCallsign.get(callsign) ?? []].map((id) => this.plans.get(id)).filter((p) => p !== void 0);
+      prev = pickMatchingPlan(candidates, m, ev.receivedAt);
+    }
+    const next = applyFlightPlanEvent(prev, ev);
+    if (!next) return null;
+    if (prev) this.unindex(prev);
+    this.plans.set(next.id, next);
+    this.index(next);
+    for (const fn of this.onChanged) fn(next);
+    return next;
+  }
+  /** Restore plans (e.g. from a database after a restart). Does not emit `changed`. */
+  load(plans, now = Date.now()) {
+    const cutoff = now - this.ttlMs;
+    let loaded = 0;
+    for (const plan of plans) {
+      if (!plan?.id || plan.updatedAt < cutoff) continue;
+      const prev = this.plans.get(plan.id);
+      if (prev) this.unindex(prev);
+      this.plans.set(plan.id, plan);
+      this.index(plan);
+      loaded++;
+    }
+    return loaded;
+  }
+  /** Best plan for a live track. Every plan sharing the Mode-S address or
+   *  callsign is a candidate (an airframe flies several legs a day); the leg
+   *  in progress, or nearest in time, wins. Cancelled plans never match. */
+  find(track, now = Date.now()) {
+    const candidates = /* @__PURE__ */ new Set();
+    if (track.icao24) {
+      for (const id of this.byIcao24.get(track.icao24.toLowerCase()) ?? []) {
+        const p = this.plans.get(id);
+        if (p) candidates.add(p);
+      }
+    }
+    const callsign = normalizeCallsign(track.callsign);
+    if (callsign) {
+      for (const id of this.byCallsign.get(callsign) ?? []) {
+        const p = this.plans.get(id);
+        if (p) candidates.add(p);
+      }
+    }
+    let best;
+    let bestScore = Infinity;
+    for (const p of candidates) {
+      if (p.status === "cancelled") continue;
+      const s = Math.abs((p.ataAt ?? p.atdAt ?? p.eobtAt ?? p.firstSeenAt) - now);
+      if (s < bestScore || s === bestScore && best && p.updatedAt > best.updatedAt) {
+        best = p;
+        bestScore = s;
+      }
+    }
+    return best;
+  }
+  /** Track with its flight-plan summary attached; unchanged when none matches.
+   *  An arrow property so it can be passed unbound, e.g. `{ attachFlightPlan: store.attach }`. */
+  attach = (track) => {
+    const plan = this.find(track);
+    if (!plan) {
+      if (!track.flightPlan) return track;
+      const { flightPlan: _drop, ...rest } = track;
+      return rest;
+    }
+    return { ...track, flightPlan: summarizeFlightPlan(plan, track.airportId) };
+  };
+  /** True if `plan` could correlate with `track`. Pair with `TrackState.refreshFlightPlans`. */
+  matches(plan, track) {
+    if (plan.icao24 && track.icao24?.toLowerCase() === plan.icao24) return true;
+    return normalizeCallsign(track.callsign) === plan.callsign;
+  }
+  list(filter = {}) {
+    const callsign = normalizeCallsign(filter.callsign);
+    const out = [...this.plans.values()].filter((p) => !filter.airportId || !p.airportId || p.airportId === filter.airportId).filter((p) => !filter.status || p.status === filter.status).filter((p) => !callsign || p.callsign.includes(callsign)).sort((a, b) => b.updatedAt - a.updatedAt);
+    return filter.limit && filter.limit > 0 ? out.slice(0, filter.limit) : out;
+  }
+  /** Drop plans past the TTL; returns their ids. */
+  sweep(now = Date.now()) {
+    const cutoff = now - this.ttlMs;
+    const removed = [];
+    for (const [id, plan] of [...this.plans]) {
+      if (plan.updatedAt >= cutoff) continue;
+      this.plans.delete(id);
+      this.unindex(plan);
+      removed.push(id);
+      for (const fn of this.onExpired) fn(id);
+    }
+    return removed;
+  }
+  startSweep(intervalMs = 10 * 6e4) {
+    if (this.sweepTimer) return;
+    this.sweepTimer = setInterval(() => this.sweep(), intervalMs);
+    this.sweepTimer.unref?.();
+  }
+  stopSweep() {
+    if (this.sweepTimer) clearInterval(this.sweepTimer);
+    this.sweepTimer = null;
+  }
+  index(plan) {
+    let ids = this.byCallsign.get(plan.callsign);
+    if (!ids) this.byCallsign.set(plan.callsign, ids = /* @__PURE__ */ new Set());
+    ids.add(plan.id);
+    if (plan.icao24) {
+      let iids = this.byIcao24.get(plan.icao24);
+      if (!iids) this.byIcao24.set(plan.icao24, iids = /* @__PURE__ */ new Set());
+      iids.add(plan.id);
+    }
+  }
+  unindex(plan) {
+    const ids = this.byCallsign.get(plan.callsign);
+    ids?.delete(plan.id);
+    if (ids?.size === 0) this.byCallsign.delete(plan.callsign);
+    if (plan.icao24) {
+      const iids = this.byIcao24.get(plan.icao24);
+      iids?.delete(plan.id);
+      if (iids?.size === 0) this.byIcao24.delete(plan.icao24);
+    }
+  }
+};
+function createFlightPlanStore(opts) {
+  return new FlightPlanStore(opts);
+}
+
+// src/movement.ts
+var AIRBORNE_ALT_FT = 300;
+var GROUND_ALT_FT = 100;
+var TAKEOFF_MIN_GS_KT = 70;
+var LANDING_MAX_GS_KT = 190;
+var DEBOUNCE_MS = 12e4;
+var MovementDetector = class {
+  phases = /* @__PURE__ */ new Map();
+  /** Feed one track state; returns a movement event on a transition. */
+  update(s) {
+    const alt = s.altitudeFt ?? null;
+    const gs = s.groundSpeedKt ?? null;
+    const looksAirborne = s.onGround === false || alt !== null && alt > AIRBORNE_ALT_FT;
+    const looksGround = s.onGround === true || alt !== null && alt < GROUND_ALT_FT;
+    const phase = this.phases.get(s.trackId);
+    if (!phase) {
+      this.phases.set(s.trackId, {
+        airborne: looksAirborne && !looksGround,
+        lastAt: s.at,
+        lastMovementAt: 0
+      });
+      return null;
+    }
+    phase.lastAt = s.at;
+    let event = null;
+    const debounced = phase.lastMovementAt !== 0 && s.at - phase.lastMovementAt < DEBOUNCE_MS;
+    if (!phase.airborne && looksAirborne && !looksGround) {
+      if ((gs ?? 0) >= TAKEOFF_MIN_GS_KT && !debounced) {
+        event = this.makeEvent(s, "takeoff");
+        phase.lastMovementAt = s.at;
+      }
+      phase.airborne = true;
+    } else if (phase.airborne && looksGround) {
+      if ((gs ?? 0) <= LANDING_MAX_GS_KT && !debounced) {
+        event = this.makeEvent(s, "landing");
+        phase.lastMovementAt = s.at;
+      }
+      phase.airborne = false;
+    }
+    return event;
+  }
+  /** Forget one track (call when its track is removed). */
+  forget(trackId) {
+    this.phases.delete(trackId);
+  }
+  /** Forget tracks not updated within maxAgeMs (call periodically). */
+  sweep(maxAgeMs, now = Date.now()) {
+    for (const [id, phase] of this.phases) {
+      if (now - phase.lastAt > maxAgeMs) this.phases.delete(id);
+    }
+  }
+  get trackedCount() {
+    return this.phases.size;
+  }
+  makeEvent(s, type) {
+    return {
+      trackId: s.trackId,
+      icao24: s.icao24 ?? null,
+      callsign: s.callsign ?? null,
+      ...s.airportId ? { airportId: s.airportId } : {},
+      type,
+      at: s.at,
+      lat: s.lat,
+      lon: s.lon
+    };
+  }
+};
+function createMovementDetector() {
+  return new MovementDetector();
+}
+
+// ../core/dist/chunk-ZYX6U3ZK.js
+import { z } from "zod";
+var positionSchema = z.object({
+  lat: z.number().min(-90).max(90),
+  lon: z.number().min(-180).max(180),
+  alt: z.number().optional(),
+  altSource: z.enum(["baro", "gnss", "mlat"]).optional(),
+  onGround: z.boolean().optional()
+});
+var velocitySchema = z.object({
+  groundSpeed: z.number().nonnegative().optional(),
+  heading: z.number().min(-1).max(361).optional(),
+  verticalRate: z.number().optional()
+});
+var flightPlanSummarySchema = z.object({
+  id: z.string(),
+  adep: z.string().optional(),
+  ades: z.string().optional(),
+  aircraftType: z.string().optional(),
+  registration: z.string().optional(),
+  eobtAt: z.number().optional(),
+  atdAt: z.number().optional(),
+  ataAt: z.number().optional(),
+  etaAt: z.number().optional(),
+  cruiseLevel: z.string().optional(),
+  route: z.string().optional(),
+  status: z.enum(["filed", "delayed", "departed", "arrived", "cancelled"]),
+  phase: z.enum(["ARRIVAL", "DEPARTURE", "OVERFLIGHT", "UNKNOWN"])
+});
+var currentTrackSchema = z.object({
+  trackId: z.string(),
+  source: z.enum(["ADSB", "ASTERIX_CAT010", "ASTERIX_CAT011", "ASTERIX_CAT020", "ASTERIX_CAT021", "ASTERIX_CAT048", "ASTERIX_CAT062", "FUSED"]),
+  icao24: z.string().nullable(),
+  callsign: z.string().nullable(),
+  squawk: z.string().nullable(),
+  targetType: z.enum(["aircraft", "vehicle", "unknown"]).optional(),
+  vehicleFleet: z.number().optional(),
+  airportId: z.string().optional(),
+  lat: z.number().min(-90).max(90).nullable(),
+  lon: z.number().min(-180).max(180).nullable(),
+  altitudeFt: z.number().nullable(),
+  groundSpeedKt: z.number().nullable(),
+  headingDeg: z.number().min(-1).max(361).nullable(),
+  verticalRateFpm: z.number().nullable(),
+  confidence: z.number().min(0).max(1),
+  lastSeenAt: z.number(),
+  status: z.enum(["active", "stale", "lost"]),
+  flightPlan: flightPlanSummarySchema.optional()
+});
+var streamEnvelopeSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("snapshot"),
+    seq: z.number(),
+    serverTime: z.number(),
+    payload: z.object({ tracks: z.array(currentTrackSchema) })
+  }),
+  z.object({
+    type: z.literal("track.updated"),
+    seq: z.number(),
+    serverTime: z.number(),
+    payload: z.object({ track: currentTrackSchema })
+  }),
+  z.object({
+    type: z.literal("track.removed"),
+    seq: z.number(),
+    serverTime: z.number(),
+    payload: z.object({ trackId: z.string(), reason: z.string() })
+  }),
+  z.object({
+    type: z.literal("source.status"),
+    seq: z.number(),
+    serverTime: z.number(),
+    payload: z.object({ sourceId: z.string(), status: z.enum(["healthy", "degraded", "offline"]) })
+  }),
+  z.object({
+    type: z.literal("stream.heartbeat"),
+    seq: z.number(),
+    serverTime: z.number(),
+    payload: z.object({}).strict()
+  }),
+  z.object({
+    type: z.literal("stream.degraded"),
+    seq: z.number(),
+    serverTime: z.number(),
+    payload: z.object({ reason: z.string(), sourceId: z.string().optional() })
+  }),
+  z.object({
+    type: z.literal("stream.error"),
+    seq: z.number(),
+    serverTime: z.number(),
+    payload: z.object({ code: z.string(), message: z.string().optional(), recoverable: z.boolean() })
+  })
+]);
+var sourceHeartbeatSchema = z.object({
+  sourceId: z.string(),
+  timestamp: z.number(),
+  packetsReceived: z.number().int(),
+  packetsSent: z.number().int(),
+  bufferFillRatio: z.number().min(0).max(1),
+  latencyMs: z.number().nonnegative(),
+  protocol: z.enum(["beast", "sbs", "asterix-cat021", "asterix-cat048"]),
+  receiverVersion: z.string().optional()
+});
+var wsSubscribeSchema = z.object({
+  type: z.literal("subscribe"),
+  bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional(),
+  source: z.enum(["fused", "normalized"]).default("fused"),
+  minConfidence: z.number().min(0).max(1).optional(),
+  maxTracks: z.number().int().min(1).max(1e4).optional(),
+  mode: z.enum(["delta", "full"]).default("delta"),
+  maxUpdateHz: z.number().min(1).max(60).default(20),
+  encoding: z.enum(["json", "msgpack"]).default("json"),
+  airportId: z.string().min(2).max(8).optional()
+});
+var wsUpdateFilterSchema = z.object({
+  type: z.literal("update-filter"),
+  bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional(),
+  minConfidence: z.number().min(0).max(1).optional(),
+  maxUpdateHz: z.number().min(1).max(60).optional(),
+  maxTracks: z.number().int().min(1).max(1e4).nullable().optional()
+});
+var apiErrorSchema = z.object({
+  ok: z.literal(false),
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    recoverable: z.boolean()
+  })
+});
+
+// src/live-server.ts
+function toText(raw) {
+  return typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+}
+function createLiveServer(opts) {
+  const { state } = opts;
+  const log = opts.logger ?? noopLogger;
+  const defaultHz = opts.defaultUpdateHz ?? 10;
+  const maxBuffered = opts.maxBufferedBytes ?? 1048576;
+  const clients = /* @__PURE__ */ new Map();
+  let seq = 0;
+  const counters = { messagesSent: 0, deltasSkipped: 0 };
+  function send(c, type, payload, droppable = false) {
+    if (c.closed) return false;
+    if (droppable && c.socket.getBufferedAmount && c.socket.getBufferedAmount() > maxBuffered) {
+      counters.deltasSkipped++;
+      return false;
+    }
+    const envelope = { type, seq: ++seq, serverTime: Date.now(), payload };
+    try {
+      c.socket.send(JSON.stringify(envelope));
+      counters.messagesSent++;
+      return true;
+    } catch (err) {
+      log.warn({ err }, "live ws: send failed");
+      return false;
+    }
+  }
+  function sendError(c, code, message) {
+    send(c, "stream.error", { code, message, recoverable: true });
+  }
+  function shouldPush(c, trackId, now) {
+    const last = c.lastPushed.get(trackId) ?? 0;
+    if (now - last < 1e3 / c.maxUpdateHz) return false;
+    c.lastPushed.set(trackId, now);
+    return true;
+  }
+  function sendSnapshot(c) {
+    const tracks = state.snapshot(c.filter);
+    c.visible = new Set(tracks.map((t) => t.trackId));
+    c.lastPushed.clear();
+    send(c, "snapshot", { tracks });
+  }
+  function hide(c, trackId, reason) {
+    if (!c.visible.delete(trackId)) return;
+    c.lastPushed.delete(trackId);
+    send(c, "track.removed", { trackId, reason });
+  }
+  function admit(c, track) {
+    const cap = c.filter.maxTracks;
+    if (cap === void 0 || c.visible.size < cap) return true;
+    let lowestId = null;
+    let lowest = trackScore(track);
+    for (const id of c.visible) {
+      const t = state.get(id);
+      if (!t) {
+        c.visible.delete(id);
+        continue;
+      }
+      const s = trackScore(t);
+      if (s < lowest) {
+        lowest = s;
+        lowestId = id;
+      }
+    }
+    if (c.visible.size < cap) return true;
+    if (!lowestId) return false;
+    hide(c, lowestId, "evicted");
+    return true;
+  }
+  const offUpdate = state.on("update", (track, info) => {
+    const now = Date.now();
+    for (const c of clients.values()) {
+      if (!c.subscribed) continue;
+      if (!matchesFilter(track, c.filter)) {
+        hide(c, track.trackId, "filtered");
+        continue;
+      }
+      if (!c.visible.has(track.trackId)) {
+        if (!admit(c, track)) continue;
+        c.visible.add(track.trackId);
+        c.lastPushed.set(track.trackId, now);
+      } else if (!info.force && !shouldPush(c, track.trackId, now)) {
+        continue;
+      }
+      if (!send(c, "track.updated", { track }, !info.force)) {
+        c.lastPushed.delete(track.trackId);
+      }
+    }
+  });
+  const offRemoved = state.on("removed", ({ trackId, reason }) => {
+    for (const c of clients.values()) {
+      if (!c.visible.has(trackId)) continue;
+      c.visible.delete(trackId);
+      c.lastPushed.delete(trackId);
+      send(c, "track.removed", { trackId, reason });
+    }
+  });
+  const heartbeat = setInterval(() => {
+    for (const c of clients.values()) if (c.ready) send(c, "stream.heartbeat", {});
+  }, opts.heartbeatMs ?? 15e3);
+  heartbeat.unref?.();
+  function handle(c, raw) {
+    let msg;
+    try {
+      msg = JSON.parse(toText(raw));
+    } catch {
+      sendError(c, "BAD_JSON", "Message is not valid JSON");
+      return;
+    }
+    if (msg["type"] === "subscribe") {
+      const parsed = wsSubscribeSchema.safeParse(msg);
+      if (!parsed.success) {
+        sendError(c, "BAD_SUBSCRIBE", "Invalid subscribe message");
+        return;
+      }
+      const sub = parsed.data;
+      c.filter = {
+        airportId: c.pinnedAirportId ?? sub.airportId,
+        bbox: sub.bbox,
+        minConfidence: sub.minConfidence ?? 0,
+        maxTracks: sub.maxTracks
+      };
+      c.maxUpdateHz = sub.maxUpdateHz;
+      c.subscribed = true;
+      sendSnapshot(c);
+    } else if (msg["type"] === "update-filter") {
+      const parsed = wsUpdateFilterSchema.safeParse(msg);
+      if (!parsed.success) {
+        sendError(c, "BAD_FILTER", "Invalid update-filter message");
+        return;
+      }
+      const upd = parsed.data;
+      if (upd.bbox !== void 0) c.filter.bbox = upd.bbox;
+      if (upd.minConfidence !== void 0) c.filter.minConfidence = upd.minConfidence;
+      if (upd.maxUpdateHz !== void 0) c.maxUpdateHz = upd.maxUpdateHz;
+      if (upd.maxTracks !== void 0) c.filter.maxTracks = upd.maxTracks ?? void 0;
+      if (c.subscribed) sendSnapshot(c);
+    }
+  }
+  return {
+    handlers: {
+      async open(ws, ctx) {
+        const c = {
+          socket: ws,
+          ready: false,
+          closed: false,
+          pending: [],
+          subscribed: false,
+          filter: {},
+          maxUpdateHz: defaultHz,
+          lastPushed: /* @__PURE__ */ new Map(),
+          visible: /* @__PURE__ */ new Set()
+        };
+        clients.set(ws, c);
+        if (!ctx.token) {
+          ws.close(4001, "Unauthorized: token required");
+          return;
+        }
+        let auth;
+        try {
+          auth = await opts.authenticate(ctx.token);
+        } catch (err) {
+          log.error({ err }, "live ws: authenticate threw");
+          auth = null;
+        }
+        if (c.closed) return;
+        if (!auth) {
+          ws.close(4003, "Unauthorized: invalid token");
+          return;
+        }
+        c.pinnedAirportId = auth.airportId;
+        c.filter.airportId = auth.airportId;
+        c.ready = true;
+        send(c, "stream.heartbeat", {});
+        const queued = c.pending.splice(0);
+        for (const raw of queued) handle(c, raw);
+      },
+      message(ws, raw) {
+        const c = clients.get(ws);
+        if (!c || c.closed) return;
+        if (!c.ready) {
+          c.pending.push(raw);
+          return;
+        }
+        handle(c, raw);
+      },
+      close(ws) {
+        const c = clients.get(ws);
+        if (c) c.closed = true;
+        clients.delete(ws);
+      }
+    },
+    sourceStatus(sourceId, status) {
+      for (const c of clients.values()) if (c.ready) send(c, "source.status", { sourceId, status });
+    },
+    degraded(reason, sourceId) {
+      for (const c of clients.values()) {
+        if (c.ready) send(c, "stream.degraded", sourceId ? { reason, sourceId } : { reason });
+      }
+    },
+    stats() {
+      let subscribed = 0;
+      for (const c of clients.values()) if (c.subscribed) subscribed++;
+      return { clients: clients.size, subscribed, ...counters };
+    },
+    stop() {
+      clearInterval(heartbeat);
+      offUpdate();
+      offRemoved();
+      for (const c of clients.values()) {
+        c.closed = true;
+        try {
+          c.socket.close(1001, "server shutting down");
+        } catch {
+        }
+      }
+      clients.clear();
+    }
+  };
+}
+export {
+  FlightPlanStore,
+  MovementDetector,
+  TrackState,
+  createFlightPlanStore,
+  createLiveServer,
+  createMovementDetector,
+  createTrackState
+};

package/package.json

@@ -1,6 +1,45 @@
-{
-  "name": "@aeroswarm/live-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@aeroswarm/live-server",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build",
+    "release": "release-it",
+    "release:dry": "release-it --dry-run",
+    "release:patch": "release-it patch --no-git.requireCleanWorkingDir",
+    "release:minor": "release-it minor --no-git.requireCleanWorkingDir",
+    "release:major": "release-it major --no-git.requireCleanWorkingDir"
+  },
+  "dependencies": {
+    "@aeroswarm/core": "^0.2.10",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "release-it": "^18.1.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6",
+    "ws": "^8.16.0",
+    "@types/ws": "^8.5.10"
+  }
+}