@squawk/adsbtop 0.2.0

package/README.md

@@ -0,0 +1,65 @@
+# @squawk/adsbtop
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE.md) [![npm](https://img.shields.io/npm/v/@squawk/adsbtop)](https://www.npmjs.com/package/@squawk/adsbtop) ![TypeScript](https://img.shields.io/badge/TypeScript-blue?logo=typescript&logoColor=white)
+
+A terminal dashboard for live ADS-B aircraft tracking, built on [`@squawk/adsb-feed`](../../packages/libs/adsb-feed). Connects to a local [dump1090-fa](https://github.com/flightaware/dump1090) station and renders tracked aircraft directly in your terminal.
+
+## Installation
+
+```bash
+npm install -g @squawk/adsbtop
+```
+
+## Usage
+
+```bash
+adsbtop --source sbs --host 192.168.1.50
+```
+
+### Options
+
+| Flag                | Description                                                                             | Default                                       |
+| ------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------- |
+| `--source <source>` | Feed to connect to: `json`, `sbs`, or `beast`                                           | `sbs`                                         |
+| `--host <host>`     | dump1090-fa station hostname/IP                                                         | `localhost`                                   |
+| `--port <port>`     | Port to connect to                                                                      | `8080` (json), `30003` (sbs), `30005` (beast) |
+| `--url <url>`       | Full `aircraft.json` URL, overriding `--host`/`--port` (`--source json` only)           | -                                             |
+| `--lat <lat>`       | Receiver latitude in decimal degrees - enables the Dist/Brg columns (requires `--lon`)  | -                                             |
+| `--lon <lon>`       | Receiver longitude in decimal degrees - enables the Dist/Brg columns (requires `--lat`) | -                                             |
+| `-h`, `--help`      | Show usage                                                                              | -                                             |
+
+### Hotkeys
+
+| Key             | Action                                                                       |
+| --------------- | ---------------------------------------------------------------------------- |
+| `Up` / `Down`   | Move the row cursor                                                          |
+| `O`             | Cycle the sort column (ICAO, callsign, altitude, ground speed, age)          |
+| `C`             | Toggle compact columns, for narrow terminals                                 |
+| `P`             | Pause/resume the table - the feed keeps running underneath                   |
+| `S`             | Search by ICAO hex, callsign, squawk, or N-number - jumps to the first match |
+| `N` / `Shift+N` | Jump to the next/previous search match                                       |
+| `M`             | Toggle the messages panel (recent new/update/lost events)                    |
+| `V`             | Toggle messages panel verbosity (new/lost only vs. every update)             |
+| `Enter` / `D`   | Show the cursor row's full detail view                                       |
+| `H`             | Toggle the help overlay                                                      |
+| `Q`             | Quit                                                                         |
+
+Aircraft squawking an emergency code (7500/7600/7700) render in bold red.
+
+### Detail view
+
+Selecting a row and pressing `Enter` or `D` opens a full field dump for that aircraft, including barometric and geometric altitude, true track and magnetic heading, and indicated/true airspeed. Fields the active source doesn't populate show as `-`.
+
+### Messages panel
+
+`M` toggles a live log of `aircraft:new`/`aircraft:update`/`aircraft:lost` events in a panel below the table. Defaults to showing only new/lost events, since `aircraft:update` fires far more often; `V` reveals every update too.
+
+### Registration lookup
+
+The `Reg` column and the detail view's `Registration` field resolve each aircraft's ICAO hex to its N-number (and make/model/operator in the detail view) using the bundled FAA registry. `S`earch also matches against the N-number. The registry loads in the background after startup - rows show `-` for a few seconds until it's ready, then populate automatically as matches are found.
+
+### Location, distance, and bearing
+
+Passing both `--lat` and `--lon` (either together or not at all) configures your receiver's own position and adds two columns: `Dist` (great-circle distance in nautical miles) and `Brg` (bearing in degrees true), computed from that position to each aircraft's current position. The detail view gets the same two fields (`Distance`/`Bearing`, shown right after `Position`). Without `--lat`/`--lon`, none of this appears at all - not the table columns, not the detail view rows. An aircraft with no position yet shows `-` until one arrives.
+
+For `--source beast`, the same location also serves as the receiver position used to decode surface (on-ground) CPR positions, which otherwise can't resolve from paired frames alone.

package/dist/aircraft-state.d.ts

@@ -0,0 +1,77 @@
+import type { Aircraft } from '@squawk/types';
+/** Which underlying feed event a {@link MessageLogEntry} records. */
+export type MessageLogEntryType = 'new' | 'update' | 'lost';
+/** One entry in the `[M]essages` panel's log, oldest first. */
+export interface MessageLogEntry {
+    /** Monotonically increasing id, stable across log trimming - used as the React list key. */
+    id: number;
+    /** Which feed event this entry records. */
+    type: MessageLogEntryType;
+    /** 24-bit ICAO hex address the event concerns. */
+    icaoHex: string;
+    /** Callsign at the time of the event, if known. */
+    callsign: string | undefined;
+    /** Unix epoch ms the event was observed. */
+    at: number;
+}
+/**
+ * Accumulated view of a live `@squawk/adsb-feed` `AircraftFeed`'s event
+ * stream: currently tracked aircraft, two bounded logs of recent events for
+ * the `[M]essages` panel, plus lightweight message-activity bookkeeping for
+ * the status header.
+ */
+export interface AircraftTableState {
+    /** Currently tracked aircraft, keyed by 24-bit ICAO hex address. */
+    aircraftByHex: Map<string, Aircraft>;
+    /** Total `aircraft:new`/`aircraft:update` events observed since the feed started. */
+    messageCount: number;
+    /** Unix epoch ms of the most recent `aircraft:new`/`aircraft:update` event, or undefined if none has arrived yet. */
+    lastMessageAt: number | undefined;
+    /** Every event type, oldest first, capped at {@link MAX_MESSAGE_LOG_ENTRIES} - backs the `[M]essages` panel's `all` verbosity. */
+    messageLog: MessageLogEntry[];
+    /**
+     * `new`/`lost` events only, oldest first, capped independently at
+     * {@link MAX_MESSAGE_LOG_ENTRIES} - backs the panel's default `newAndLost`
+     * verbosity. Kept as its own log rather than derived by filtering
+     * `messageLog`: `update` events fire far more often than `new`/`lost`, so
+     * a shared cap gets dominated by update volume and evicts a still-relevant
+     * new/lost entry within seconds of real traffic, even though nothing
+     * about it changed - toggling verbosity back to `newAndLost` would then
+     * show fewer entries than a moment before, for no reason visible to the
+     * user. A separate cap means `update` volume can never evict a
+     * `new`/`lost` entry.
+     */
+    newAndLostLog: MessageLogEntry[];
+    /** Next {@link MessageLogEntry.id} to assign - kept separate from either log's length so ids stay stable once old entries are trimmed off the front. */
+    nextLogId: number;
+}
+/** An update or removal observed on the underlying `AircraftFeed`. */
+export type AircraftStateAction = {
+    type: 'message';
+    kind: 'new' | 'update';
+    aircraft: Aircraft;
+    at: number;
+} | {
+    type: 'lost';
+    icaoHex: string;
+    callsign: string | undefined;
+    at: number;
+};
+/** Empty {@link AircraftTableState}, before any feed event has arrived. */
+export declare const initialAircraftState: AircraftTableState;
+/**
+ * Reducer accumulating {@link AircraftStateAction}s into an {@link AircraftTableState}.
+ * Pure and side-effect-free - the caller supplies `at` from `Date.now()` at
+ * dispatch time, rather than this function reading the clock itself, so it
+ * stays trivially testable with fixed timestamps. Every action appends a
+ * {@link MessageLogEntry}, including a `lost` action for an ICAO hex this
+ * state never tracked - that shouldn't happen against a real `AircraftFeed`,
+ * but the log's job is showing what events actually arrived, not judging
+ * whether they were expected.
+ *
+ * @param state - The current accumulated state.
+ * @param action - The event to apply.
+ * @returns The next state. Always a new `aircraftByHex` map when it changes, so React's `useReducer` sees a fresh reference.
+ */
+export declare function aircraftStateReducer(state: AircraftTableState, action: AircraftStateAction): AircraftTableState;
+//# sourceMappingURL=aircraft-state.d.ts.map

package/dist/aircraft-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aircraft-state.d.ts","sourceRoot":"","sources":["../src/aircraft-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5D,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,4FAA4F;IAC5F,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,IAAI,EAAE,mBAAmB,CAAC;IAC1B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;CACZ;AASD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACrC,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB,qHAAqH;IACrH,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,kIAAkI;IAClI,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,eAAe,EAAE,CAAC;IACjC,wJAAwJ;IACxJ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,EAAE,kBAOlC,CAAC;AAiBF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,mBAAmB,GAC1B,kBAAkB,CA4CpB"}

package/dist/aircraft-state.js

@@ -0,0 +1,87 @@
+/**
+ * Maximum {@link MessageLogEntry} rows retained. Oldest entries are dropped
+ * once exceeded, so the log stays a bounded "recent activity" view rather
+ * than growing unbounded for a long-running session.
+ */
+const MAX_MESSAGE_LOG_ENTRIES = 200;
+/** Empty {@link AircraftTableState}, before any feed event has arrived. */
+export const initialAircraftState = {
+    aircraftByHex: new Map(),
+    messageCount: 0,
+    lastMessageAt: undefined,
+    messageLog: [],
+    newAndLostLog: [],
+    nextLogId: 0,
+};
+/**
+ * Appends `entry` to `log`, dropping the oldest entry once
+ * {@link MAX_MESSAGE_LOG_ENTRIES} is exceeded.
+ *
+ * @param log - The current log, oldest first.
+ * @param entry - The entry to append.
+ * @returns A new array with `entry` appended, trimmed to the max length.
+ */
+function appendLogEntry(log, entry) {
+    const next = [...log, entry];
+    return next.length > MAX_MESSAGE_LOG_ENTRIES
+        ? next.slice(next.length - MAX_MESSAGE_LOG_ENTRIES)
+        : next;
+}
+/**
+ * Reducer accumulating {@link AircraftStateAction}s into an {@link AircraftTableState}.
+ * Pure and side-effect-free - the caller supplies `at` from `Date.now()` at
+ * dispatch time, rather than this function reading the clock itself, so it
+ * stays trivially testable with fixed timestamps. Every action appends a
+ * {@link MessageLogEntry}, including a `lost` action for an ICAO hex this
+ * state never tracked - that shouldn't happen against a real `AircraftFeed`,
+ * but the log's job is showing what events actually arrived, not judging
+ * whether they were expected.
+ *
+ * @param state - The current accumulated state.
+ * @param action - The event to apply.
+ * @returns The next state. Always a new `aircraftByHex` map when it changes, so React's `useReducer` sees a fresh reference.
+ */
+export function aircraftStateReducer(state, action) {
+    switch (action.type) {
+        case 'message': {
+            const aircraftByHex = new Map(state.aircraftByHex);
+            aircraftByHex.set(action.aircraft.icaoHex, action.aircraft);
+            const logEntry = {
+                id: state.nextLogId,
+                type: action.kind,
+                icaoHex: action.aircraft.icaoHex,
+                callsign: action.aircraft.callsign,
+                at: action.at,
+            };
+            const newAndLostLog = action.kind === 'new' ? appendLogEntry(state.newAndLostLog, logEntry) : state.newAndLostLog;
+            return {
+                aircraftByHex,
+                messageCount: state.messageCount + 1,
+                lastMessageAt: action.at,
+                messageLog: appendLogEntry(state.messageLog, logEntry),
+                newAndLostLog,
+                nextLogId: state.nextLogId + 1,
+            };
+        }
+        case 'lost': {
+            const logEntry = {
+                id: state.nextLogId,
+                type: 'lost',
+                icaoHex: action.icaoHex,
+                callsign: action.callsign,
+                at: action.at,
+            };
+            const messageLog = appendLogEntry(state.messageLog, logEntry);
+            const newAndLostLog = appendLogEntry(state.newAndLostLog, logEntry);
+            const nextLogId = state.nextLogId + 1;
+            if (!state.aircraftByHex.has(action.icaoHex)) {
+                return { ...state, messageLog, newAndLostLog, nextLogId };
+            }
+            const aircraftByHex = new Map(state.aircraftByHex);
+            aircraftByHex.delete(action.icaoHex);
+            return { ...state, aircraftByHex, messageLog, newAndLostLog, nextLogId };
+        }
+        default:
+            return state;
+    }
+}

package/dist/app.d.ts

@@ -0,0 +1,41 @@
+import type { ReactElement } from 'react';
+import type { AircraftFeed } from '@squawk/adsb-feed';
+import type { Coordinates } from '@squawk/types';
+import type { FeedSource } from './cli-args.js';
+import type { RegistryDataLoader } from './use-icao-registry.js';
+/** Props for {@link App}. */
+export interface AppProps {
+    /** The live feed to subscribe to - already constructed for the CLI's selected source. */
+    feed: AircraftFeed;
+    /** Feed source in use, for the status header. */
+    source: FeedSource;
+    /** Station host, for the status header. */
+    host: string;
+    /** Station port, for the status header. */
+    port: number;
+    /** Loader for the bundled registry dataset used for registration enrichment. Defaults to a real dynamic import of `@squawk/icao-registry-data`; overridable in tests. */
+    registryDataLoader?: RegistryDataLoader;
+    /** Configured receiver location (`--lat`/`--lon`), if any. Enables the table's Dist/Brg columns when set. */
+    location: Coordinates | undefined;
+}
+/**
+ * adsbtop's root component: subscribes to the feed, owns display state
+ * (pause, compact columns, sort, cursor, search, messages, and which main
+ * panel is showing), wires the hotkey bar, and renders the status header,
+ * main panel, optional messages panel, optional search prompt, and hotkey
+ * bar.
+ *
+ * `[P]ause` freezes the table's displayed rows (the feed keeps running
+ * underneath - resuming immediately jumps to current state, doesn't replay
+ * what was missed). Implemented as a React "adjust state during render"
+ * pattern (comparing the live feed's aircraft-array reference against what's
+ * displayed, copying over only while not paused), not a `useEffect`, since
+ * an effect-based version of this exact pattern trips
+ * `react-hooks/set-state-in-effect` and cascades an extra render. The cursor
+ * row's auto-selection uses the same render-time-adjustment pattern for the
+ * same reason.
+ *
+ * @param props - The feed to display and its connection details.
+ */
+export declare function App(props: AppProps): ReactElement;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAG1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAiBhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAUjE,6BAA6B;AAC7B,MAAM,WAAW,QAAQ;IACvB,yFAAyF;IACzF,IAAI,EAAE,YAAY,CAAC;IACnB,iDAAiD;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,yKAAyK;IACzK,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,6GAA6G;IAC7G,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,YAAY,CAgMjD"}

package/dist/app.js

@@ -0,0 +1,166 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, useApp, useInput } from 'ink';
+import { useEffect, useMemo, useState } from 'react';
+import { nextSortKey, sortAircraft, visibleColumns } from './columns.js';
+import { AircraftTable } from './components/aircraft-table.js';
+import { DetailView } from './components/detail-view.js';
+import { HelpOverlay } from './components/help-overlay.js';
+import { HotkeyBar } from './components/hotkey-bar.js';
+import { MessagesPanel } from './components/messages-panel.js';
+import { SearchBar } from './components/search-bar.js';
+import { StatusHeader } from './components/status-header.js';
+import { enrichAircraftList } from './registration-cache.js';
+import { findMatchIcaoHex } from './search.js';
+import { moveSelection } from './selection.js';
+import { useAircraftFeed } from './use-aircraft-feed.js';
+import { useIcaoRegistry } from './use-icao-registry.js';
+/** How often the age column and status-header "last update" text refresh. */
+const CLOCK_TICK_MS = 1000;
+/** Sort key adsbtop starts with. */
+const INITIAL_SORT_KEY = 'icaoHex';
+/**
+ * adsbtop's root component: subscribes to the feed, owns display state
+ * (pause, compact columns, sort, cursor, search, messages, and which main
+ * panel is showing), wires the hotkey bar, and renders the status header,
+ * main panel, optional messages panel, optional search prompt, and hotkey
+ * bar.
+ *
+ * `[P]ause` freezes the table's displayed rows (the feed keeps running
+ * underneath - resuming immediately jumps to current state, doesn't replay
+ * what was missed). Implemented as a React "adjust state during render"
+ * pattern (comparing the live feed's aircraft-array reference against what's
+ * displayed, copying over only while not paused), not a `useEffect`, since
+ * an effect-based version of this exact pattern trips
+ * `react-hooks/set-state-in-effect` and cascades an extra render. The cursor
+ * row's auto-selection uses the same render-time-adjustment pattern for the
+ * same reason.
+ *
+ * @param props - The feed to display and its connection details.
+ */
+export function App(props) {
+    const { exit } = useApp();
+    const view = useAircraftFeed(props.feed);
+    const registry = useIcaoRegistry(props.registryDataLoader);
+    const [registrationCache] = useState(() => new Map());
+    const enrichedAircraft = useMemo(() => enrichAircraftList(view.aircraft, registry, registrationCache), [view.aircraft, registry, registrationCache]);
+    const [paused, setPaused] = useState(false);
+    const [compact, setCompact] = useState(false);
+    const [panel, setPanel] = useState('table');
+    const [sortKey, setSortKey] = useState(INITIAL_SORT_KEY);
+    const [now, setNow] = useState(() => Date.now());
+    const [displayedAircraft, setDisplayedAircraft] = useState(enrichedAircraft);
+    const [selectedIcaoHex, setSelectedIcaoHex] = useState(undefined);
+    const [showMessages, setShowMessages] = useState(false);
+    const [messageVerbosity, setMessageVerbosity] = useState('newAndLost');
+    const [searching, setSearching] = useState(false);
+    const [searchQuery, setSearchQuery] = useState('');
+    const [submittedSearchQuery, setSubmittedSearchQuery] = useState(undefined);
+    useEffect(() => {
+        const handle = setInterval(() => setNow(Date.now()), CLOCK_TICK_MS);
+        return () => clearInterval(handle);
+    }, []);
+    if (!paused && enrichedAircraft !== displayedAircraft) {
+        setDisplayedAircraft(enrichedAircraft);
+    }
+    const sortedAircraft = useMemo(() => sortAircraft(displayedAircraft, sortKey), [displayedAircraft, sortKey]);
+    const columns = useMemo(() => visibleColumns(compact, props.location), [compact, props.location]);
+    const firstAircraft = sortedAircraft[0];
+    if (selectedIcaoHex === undefined && firstAircraft !== undefined) {
+        setSelectedIcaoHex(firstAircraft.icaoHex);
+    }
+    const selectedAircraft = sortedAircraft.find((aircraft) => aircraft.icaoHex === selectedIcaoHex);
+    function handleSearchSubmit(query) {
+        setSearching(false);
+        const trimmed = query.trim();
+        if (trimmed === '') {
+            setSubmittedSearchQuery(undefined);
+            return;
+        }
+        setSubmittedSearchQuery(trimmed);
+        const match = findMatchIcaoHex(sortedAircraft, trimmed, selectedIcaoHex, 1);
+        if (match !== undefined) {
+            setSelectedIcaoHex(match);
+        }
+    }
+    useInput((input, key) => {
+        if (input === 'q' || input === 'Q') {
+            exit();
+            return;
+        }
+        if (key.escape) {
+            if (panel !== 'table') {
+                setPanel('table');
+            }
+            return;
+        }
+        if (key.upArrow) {
+            setSelectedIcaoHex((prev) => moveSelection(sortedAircraft, prev, -1));
+            return;
+        }
+        if (key.downArrow) {
+            setSelectedIcaoHex((prev) => moveSelection(sortedAircraft, prev, 1));
+            return;
+        }
+        if (key.return) {
+            if (selectedAircraft !== undefined) {
+                setPanel((prev) => (prev === 'detail' ? 'table' : 'detail'));
+            }
+            return;
+        }
+        switch (input) {
+            case 'p':
+            case 'P':
+                setPaused((prev) => !prev);
+                break;
+            case 'c':
+            case 'C':
+                setCompact((prev) => !prev);
+                break;
+            case 'h':
+            case 'H':
+                setPanel((prev) => (prev === 'help' ? 'table' : 'help'));
+                break;
+            case 'o':
+            case 'O':
+                setSortKey((prev) => nextSortKey(prev));
+                break;
+            case 'd':
+            case 'D':
+                if (selectedAircraft !== undefined) {
+                    setPanel((prev) => (prev === 'detail' ? 'table' : 'detail'));
+                }
+                break;
+            case 's':
+            case 'S':
+                setSearching(true);
+                setSearchQuery('');
+                break;
+            case 'm':
+            case 'M':
+                setShowMessages((prev) => !prev);
+                break;
+            case 'v':
+            case 'V':
+                setMessageVerbosity((prev) => (prev === 'all' ? 'newAndLost' : 'all'));
+                break;
+            case 'n':
+                if (submittedSearchQuery !== undefined) {
+                    setSelectedIcaoHex((prev) => findMatchIcaoHex(sortedAircraft, submittedSearchQuery, prev, 1) ?? prev);
+                }
+                break;
+            case 'N':
+                if (submittedSearchQuery !== undefined) {
+                    setSelectedIcaoHex((prev) => findMatchIcaoHex(sortedAircraft, submittedSearchQuery, prev, -1) ?? prev);
+                }
+                break;
+            default:
+                break;
+        }
+    }, { isActive: !searching });
+    useInput((_input, key) => {
+        if (key.escape) {
+            setSearching(false);
+        }
+    }, { isActive: searching });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(StatusHeader, { source: props.source, host: props.host, port: props.port, aircraftCount: view.aircraft.length, messageRatePerSec: view.messageRatePerSec, lastMessageAt: view.lastMessageAt, nowMs: now, paused: paused }), panel === 'help' ? (_jsx(HelpOverlay, {})) : panel === 'detail' && selectedAircraft !== undefined ? (_jsx(DetailView, { aircraft: selectedAircraft, nowMs: now, location: props.location })) : (_jsx(AircraftTable, { aircraft: sortedAircraft, columns: columns, nowMs: now, sortKey: sortKey, selectedIcaoHex: selectedIcaoHex })), showMessages ? (_jsx(MessagesPanel, { entries: messageVerbosity === 'newAndLost' ? view.newAndLostLog : view.messageLog, verbosity: messageVerbosity })) : undefined, searching ? (_jsx(SearchBar, { query: searchQuery, onChange: setSearchQuery, onSubmit: handleSearchSubmit })) : undefined, _jsx(HotkeyBar, { paused: paused, showMessages: showMessages, hasActiveSearch: submittedSearchQuery !== undefined })] }));
+}

package/dist/cli-args.d.ts

@@ -0,0 +1,43 @@
+import type { Coordinates } from '@squawk/types';
+/** Which dump1090-fa output adsbtop connects to. */
+export type FeedSource = 'json' | 'sbs' | 'beast';
+/** Default TCP/HTTP port per {@link FeedSource}, matching dump1090-fa's own defaults. */
+export declare const DEFAULT_PORT_BY_SOURCE: Record<FeedSource, number>;
+/** Parsed and validated CLI options for the `adsbtop` command. */
+export interface CliOptions {
+    /** Whether `--help` was passed. When true, every other field is a placeholder and the caller should print usage and exit without starting a feed. */
+    help: boolean;
+    /** Which dump1090-fa output to connect to. */
+    source: FeedSource;
+    /** Hostname or IP address of the dump1090-fa station. */
+    host: string;
+    /** TCP/HTTP port to connect to. Defaults to {@link DEFAULT_PORT_BY_SOURCE} for the selected source. */
+    port: number;
+    /** Full override URL for the `json` source's `aircraft.json` endpoint. Undefined for `sbs`/`beast`, and undefined for `json` unless `--url` was passed explicitly. */
+    url: string | undefined;
+    /**
+     * The receiving station's own position, from `--lat`/`--lon`. When set,
+     * the table's Dist/Brg columns compute distance and bearing from this
+     * point to each aircraft, and for `--source beast` the same value also
+     * feeds `BeastFeedOptions.receiverPosition` for surface CPR decoding.
+     * Undefined unless both `--lat` and `--lon` were passed.
+     */
+    location: Coordinates | undefined;
+}
+/** A `parseCliArgs` failure: the reason `argv` could not be turned into {@link CliOptions}. */
+export interface CliArgsError {
+    /** Human-readable message describing what was wrong with `argv`, suitable for printing directly to stderr. */
+    message: string;
+}
+/** Usage text printed for `--help`/`-h`, and on an argument error. */
+export declare const USAGE: string;
+/**
+ * Parses and validates `adsbtop`'s command-line arguments. Returns a result
+ * type rather than throwing, so callers (and tests) can handle a bad
+ * argument the same way as any other expected outcome.
+ *
+ * @param argv - Argument list, excluding the `node`/script entries (i.e. `process.argv.slice(2)`).
+ * @returns The parsed options, or a {@link CliArgsError} describing the first problem found.
+ */
+export declare function parseCliArgs(argv: string[]): CliOptions | CliArgsError;
+//# sourceMappingURL=cli-args.d.ts.map

package/dist/cli-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAElD,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAI7D,CAAC;AAEF,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,qJAAqJ;IACrJ,IAAI,EAAE,OAAO,CAAC;IACd,8CAA8C;IAC9C,MAAM,EAAE,UAAU,CAAC;IACnB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,IAAI,EAAE,MAAM,CAAC;IACb,sKAAsK;IACtK,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;CACnC;AAED,+FAA+F;AAC/F,MAAM,WAAW,YAAY;IAC3B,8GAA8G;IAC9G,OAAO,EAAE,MAAM,CAAC;CACjB;AAuCD,sEAAsE;AACtE,eAAO,MAAM,KAAK,QAUjB,CAAC;AAiCF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,GAAG,YAAY,CAiEtE"}

package/dist/cli-args.js

@@ -0,0 +1,150 @@
+import { parseArgs } from 'node:util';
+/** Default TCP/HTTP port per {@link FeedSource}, matching dump1090-fa's own defaults. */
+export const DEFAULT_PORT_BY_SOURCE = {
+    json: 8080,
+    sbs: 30003,
+    beast: 30005,
+};
+const DEFAULT_HOST = 'localhost';
+const DEFAULT_SOURCE = 'sbs';
+const NEGATIVE_NUMBER = /^-\d+(\.\d+)?$/;
+function isFeedSource(value) {
+    return value === 'json' || value === 'sbs' || value === 'beast';
+}
+/**
+ * Node's `parseArgs` rejects `--lon -73.7781` as an ambiguous option value
+ * (a bare token starting with `-` looks like another flag), requiring the
+ * awkward `--lon=-73.7781` form instead - a real problem here since most
+ * real-world longitudes (and some latitudes) are negative. Rewrites a
+ * `--lat`/`--lon` immediately followed by a bare negative number into the
+ * `=` form before parsing, so the natural `--lon -73.7781` spelling works.
+ *
+ * @param argv - Raw argument list, as passed to {@link parseCliArgs}.
+ * @returns `argv` with negative `--lat`/`--lon` values rewritten to `--flag=value` form.
+ */
+function normalizeNegativeLocationArgs(argv) {
+    const normalized = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined) {
+            continue;
+        }
+        const next = argv[i + 1];
+        if ((arg === '--lat' || arg === '--lon') && next !== undefined && NEGATIVE_NUMBER.test(next)) {
+            normalized.push(`${arg}=${next}`);
+            i++;
+        }
+        else {
+            normalized.push(arg);
+        }
+    }
+    return normalized;
+}
+/** Usage text printed for `--help`/`-h`, and on an argument error. */
+export const USAGE = `Usage: adsbtop [options]
+
+Options:
+  --source <json|sbs|beast>  Feed to connect to (default: ${DEFAULT_SOURCE})
+  --host <host>              dump1090-fa station hostname/IP (default: ${DEFAULT_HOST})
+  --port <port>              Port to connect to (default: 8080 json, 30003 sbs, 30005 beast)
+  --url <url>                Full aircraft.json URL, overriding --host/--port (source=json only)
+  --lat <lat>                Receiver latitude in decimal degrees - enables Dist/Brg columns (requires --lon)
+  --lon <lon>                Receiver longitude in decimal degrees - enables Dist/Brg columns (requires --lat)
+  -h, --help                 Show this help message
+`;
+/**
+ * Parses and validates `--lat`/`--lon` into a {@link Coordinates}. Both must
+ * be given together; either alone is an error. Returns `{ location:
+ * undefined }` when neither was passed, since omitting location entirely is
+ * valid and distinct from an invalid one.
+ *
+ * @param rawLat - Raw `--lat` value, if passed.
+ * @param rawLon - Raw `--lon` value, if passed.
+ * @returns The parsed location (possibly undefined), or a {@link CliArgsError}.
+ */
+function parseLocation(rawLat, rawLon) {
+    if (rawLat === undefined && rawLon === undefined) {
+        return { location: undefined };
+    }
+    if (rawLat === undefined || rawLon === undefined) {
+        return { message: '--lat and --lon must be provided together.' };
+    }
+    const lat = Number(rawLat);
+    if (!Number.isFinite(lat) || lat < -90 || lat > 90) {
+        return { message: `Invalid --lat "${rawLat}" - expected a number between -90 and 90.` };
+    }
+    const lon = Number(rawLon);
+    if (!Number.isFinite(lon) || lon < -180 || lon > 180) {
+        return { message: `Invalid --lon "${rawLon}" - expected a number between -180 and 180.` };
+    }
+    return { location: { lat, lon } };
+}
+/**
+ * Parses and validates `adsbtop`'s command-line arguments. Returns a result
+ * type rather than throwing, so callers (and tests) can handle a bad
+ * argument the same way as any other expected outcome.
+ *
+ * @param argv - Argument list, excluding the `node`/script entries (i.e. `process.argv.slice(2)`).
+ * @returns The parsed options, or a {@link CliArgsError} describing the first problem found.
+ */
+export function parseCliArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: normalizeNegativeLocationArgs(argv),
+            options: {
+                source: { type: 'string', default: DEFAULT_SOURCE },
+                host: { type: 'string', default: DEFAULT_HOST },
+                port: { type: 'string' },
+                url: { type: 'string' },
+                lat: { type: 'string' },
+                lon: { type: 'string' },
+                help: { type: 'boolean', short: 'h', default: false },
+            },
+            strict: true,
+        });
+    }
+    catch (error) {
+        return { message: error instanceof Error ? error.message : String(error) };
+    }
+    const { values } = parsed;
+    if (values.help === true) {
+        return {
+            help: true,
+            source: DEFAULT_SOURCE,
+            host: DEFAULT_HOST,
+            port: DEFAULT_PORT_BY_SOURCE[DEFAULT_SOURCE],
+            url: undefined,
+            location: undefined,
+        };
+    }
+    const parsedLocation = parseLocation(values.lat, values.lon);
+    if ('message' in parsedLocation) {
+        return parsedLocation;
+    }
+    const rawSource = values.source ?? DEFAULT_SOURCE;
+    if (!isFeedSource(rawSource)) {
+        return { message: `Invalid --source "${rawSource}" - expected json, sbs, or beast.` };
+    }
+    let port = DEFAULT_PORT_BY_SOURCE[rawSource];
+    if (values.port !== undefined) {
+        const parsedPort = Number(values.port);
+        if (!Number.isInteger(parsedPort) || parsedPort <= 0 || parsedPort > 65535) {
+            return {
+                message: `Invalid --port "${values.port}" - expected an integer between 1 and 65535.`,
+            };
+        }
+        port = parsedPort;
+    }
+    if (values.url !== undefined && rawSource !== 'json') {
+        return { message: '--url is only valid with --source json.' };
+    }
+    return {
+        help: false,
+        source: rawSource,
+        host: values.host ?? DEFAULT_HOST,
+        port,
+        url: values.url,
+        location: parsedLocation.location,
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.tsx"],"names":[],"mappings":""}