@squawk/adsbtop 0.2.0

package/dist/components/status-header.d.ts

@@ -0,0 +1,17 @@
+import type { ReactElement } from 'react';
+import type { StatusLineInfo } from '../status-line.js';
+/** Props for {@link StatusHeader}. */
+export interface StatusHeaderProps extends StatusLineInfo {
+    /** Whether the table is currently paused. */
+    paused: boolean;
+}
+/**
+ * Connection and activity summary shown above the aircraft table:
+ * source/host/port, tracked aircraft count, message rate, and time since the
+ * last update, followed by a blank line (same background) to give the table
+ * header row below it some breathing room.
+ *
+ * @param props - The connection/activity state to display.
+ */
+export declare function StatusHeader(props: StatusHeaderProps): ReactElement;
+//# sourceMappingURL=status-header.d.ts.map

package/dist/components/status-header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-header.d.ts","sourceRoot":"","sources":["../../src/components/status-header.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAG1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,sCAAsC;AACtC,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAiBnE"}

package/dist/components/status-header.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { formatStatusLine } from '../status-line.js';
+/**
+ * Connection and activity summary shown above the aircraft table:
+ * source/host/port, tracked aircraft count, message rate, and time since the
+ * last update, followed by a blank line (same background) to give the table
+ * header row below it some breathing room.
+ *
+ * @param props - The connection/activity state to display.
+ */
+export function StatusHeader(props) {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { width: "100%", backgroundColor: "blue", children: [_jsx(Text, { bold: true, color: "white", children: 'adsbtop  ' }), _jsx(Text, { color: "white", children: formatStatusLine(props) }), props.paused ? (_jsx(Text, { bold: true, color: "yellow", children: '  PAUSED' })) : undefined] }), _jsx(Box, { width: "100%", backgroundColor: "blue", height: 1 })] }));
+}

package/dist/create-feed.d.ts

@@ -0,0 +1,33 @@
+import { createBeastAircraftFeed, createJsonAircraftFeed, createSbsAircraftFeed } from '@squawk/adsb-feed';
+import type { AircraftFeed } from '@squawk/adsb-feed';
+import type { CliOptions } from './cli-args.js';
+/** The three feed factories `buildFeed` chooses between, injectable so tests can substitute fakes without touching real sockets/HTTP. */
+export interface FeedFactories {
+    /** Factory for the `json` source. */
+    createJsonAircraftFeed: typeof createJsonAircraftFeed;
+    /** Factory for the `sbs` source. */
+    createSbsAircraftFeed: typeof createSbsAircraftFeed;
+    /** Factory for the `beast` source. */
+    createBeastAircraftFeed: typeof createBeastAircraftFeed;
+}
+/** The real `@squawk/adsb-feed` factories, used outside of tests. */
+export declare const DEFAULT_FEED_FACTORIES: FeedFactories;
+/**
+ * Builds the `aircraft.json` URL for the `json` source from `--host`/`--port`,
+ * used unless `--url` was passed explicitly.
+ *
+ * @param host - Station hostname or IP address.
+ * @param port - HTTP port serving `aircraft.json`.
+ * @returns The full endpoint URL.
+ */
+export declare function buildJsonUrl(host: string, port: number): string;
+/**
+ * Constructs the `AircraftFeed` for the CLI's selected source and connection
+ * options.
+ *
+ * @param cli - Parsed, validated CLI options (must have `help: false`).
+ * @param factories - Feed factories to use; defaults to the real `@squawk/adsb-feed` factories.
+ * @returns An `AircraftFeed` ready to `start()`.
+ */
+export declare function buildFeed(cli: CliOptions, factories?: FeedFactories): AircraftFeed;
+//# sourceMappingURL=create-feed.d.ts.map

package/dist/create-feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-feed.d.ts","sourceRoot":"","sources":["../src/create-feed.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,yIAAyI;AACzI,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,oCAAoC;IACpC,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;IACpD,sCAAsC;IACtC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;CACzD;AAED,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,EAAE,aAIpC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,UAAU,EACf,SAAS,GAAE,aAAsC,GAChD,YAAY,CAad"}

package/dist/create-feed.js

@@ -0,0 +1,40 @@
+import { createBeastAircraftFeed, createJsonAircraftFeed, createSbsAircraftFeed, } from '@squawk/adsb-feed';
+/** The real `@squawk/adsb-feed` factories, used outside of tests. */
+export const DEFAULT_FEED_FACTORIES = {
+    createJsonAircraftFeed,
+    createSbsAircraftFeed,
+    createBeastAircraftFeed,
+};
+/**
+ * Builds the `aircraft.json` URL for the `json` source from `--host`/`--port`,
+ * used unless `--url` was passed explicitly.
+ *
+ * @param host - Station hostname or IP address.
+ * @param port - HTTP port serving `aircraft.json`.
+ * @returns The full endpoint URL.
+ */
+export function buildJsonUrl(host, port) {
+    return `http://${host}:${port}/data/aircraft.json`;
+}
+/**
+ * Constructs the `AircraftFeed` for the CLI's selected source and connection
+ * options.
+ *
+ * @param cli - Parsed, validated CLI options (must have `help: false`).
+ * @param factories - Feed factories to use; defaults to the real `@squawk/adsb-feed` factories.
+ * @returns An `AircraftFeed` ready to `start()`.
+ */
+export function buildFeed(cli, factories = DEFAULT_FEED_FACTORIES) {
+    switch (cli.source) {
+        case 'json':
+            return factories.createJsonAircraftFeed({ url: cli.url ?? buildJsonUrl(cli.host, cli.port) });
+        case 'sbs':
+            return factories.createSbsAircraftFeed({ host: cli.host, port: cli.port });
+        case 'beast':
+            return factories.createBeastAircraftFeed({
+                host: cli.host,
+                port: cli.port,
+                ...(cli.location !== undefined ? { receiverPosition: cli.location } : {}),
+            });
+    }
+}

package/dist/detail-fields.d.ts

@@ -0,0 +1,23 @@
+import type { Aircraft, Coordinates } from '@squawk/types';
+/** One labeled row in the aircraft detail view. */
+export interface DetailField {
+    /** Row label. */
+    label: string;
+    /** Formatted value, or `'-'` if not populated by the current source. */
+    value: string;
+}
+/**
+ * Builds the full labeled field list for the `[Enter]/[D]etail` view: every
+ * `Aircraft` field, in a fixed order, formatted for display with `'-'` for
+ * anything the active source hasn't populated. Deliberately does not
+ * collapse baro/geo altitude or true/magnetic heading into one value the way
+ * the table's compact columns do - showing both is the point of a "full
+ * field dump" view.
+ *
+ * @param aircraft - The selected aircraft to build fields for.
+ * @param nowMs - Current time, for the "last seen" age.
+ * @param location - The configured receiver location (`--lat`/`--lon`), if any. Adds Distance/Bearing rows after Position when set; omitted entirely otherwise, matching the table's Dist/Brg columns.
+ * @returns Labeled rows in display order.
+ */
+export declare function buildDetailFields(aircraft: Aircraft, nowMs: number, location: Coordinates | undefined): DetailField[];
+//# sourceMappingURL=detail-fields.d.ts.map

package/dist/detail-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detail-fields.d.ts","sourceRoot":"","sources":["../src/detail-fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAiC,WAAW,EAAY,MAAM,eAAe,CAAC;AAYpG,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;CACf;AAgCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,WAAW,GAAG,SAAS,GAChC,WAAW,EAAE,CA8Bf"}

package/dist/detail-fields.js

@@ -0,0 +1,68 @@
+import { formatAge, formatBearing, formatDistance, formatGroundSpeed, formatOnGround, formatVerticalRate, } from './format.js';
+import { bearingToAircraftDeg, distanceToAircraftNm } from './location.js';
+function formatFeet(valueFt) {
+    return valueFt === undefined ? '-' : `${Math.round(valueFt)}ft`;
+}
+function formatKnots(valueKt) {
+    return valueKt === undefined ? '-' : `${Math.round(valueKt)}kt`;
+}
+function formatDegrees(valueDeg) {
+    return valueDeg === undefined ? '-' : `${Math.round(valueDeg)}°`;
+}
+function formatPosition(position) {
+    return position === undefined ? '-' : `${position.lat.toFixed(4)}, ${position.lon.toFixed(4)}`;
+}
+function formatRegistration(registration) {
+    if (registration === undefined) {
+        return '-';
+    }
+    const makeModel = [registration.make, registration.model]
+        .filter((part) => part !== undefined)
+        .join(' ');
+    return makeModel === '' ? registration.registration : `${registration.registration} ${makeModel}`;
+}
+function formatAirport(airport) {
+    return airport === undefined ? '-' : (airport.icao ?? airport.faaId);
+}
+/**
+ * Builds the full labeled field list for the `[Enter]/[D]etail` view: every
+ * `Aircraft` field, in a fixed order, formatted for display with `'-'` for
+ * anything the active source hasn't populated. Deliberately does not
+ * collapse baro/geo altitude or true/magnetic heading into one value the way
+ * the table's compact columns do - showing both is the point of a "full
+ * field dump" view.
+ *
+ * @param aircraft - The selected aircraft to build fields for.
+ * @param nowMs - Current time, for the "last seen" age.
+ * @param location - The configured receiver location (`--lat`/`--lon`), if any. Adds Distance/Bearing rows after Position when set; omitted entirely otherwise, matching the table's Dist/Brg columns.
+ * @returns Labeled rows in display order.
+ */
+export function buildDetailFields(aircraft, nowMs, location) {
+    const locationFields = location === undefined
+        ? []
+        : [
+            { label: 'Distance', value: formatDistance(distanceToAircraftNm(location, aircraft)) },
+            { label: 'Bearing', value: formatBearing(bearingToAircraftDeg(location, aircraft)) },
+        ];
+    return [
+        { label: 'ICAO', value: aircraft.icaoHex },
+        { label: 'Callsign', value: aircraft.callsign ?? '-' },
+        { label: 'Squawk', value: aircraft.squawk ?? '-' },
+        { label: 'Registration', value: formatRegistration(aircraft.registration) },
+        { label: 'Position', value: formatPosition(aircraft.position) },
+        ...locationFields,
+        { label: 'Baro altitude', value: formatFeet(aircraft.position?.baroAltitudeFt) },
+        { label: 'Geo altitude', value: formatFeet(aircraft.position?.geoAltitudeFt) },
+        { label: 'Ground speed', value: formatGroundSpeed(aircraft) },
+        { label: 'Indicated airspeed', value: formatKnots(aircraft.indicatedAirspeedKt) },
+        { label: 'True airspeed', value: formatKnots(aircraft.trueAirspeedKt) },
+        { label: 'True track', value: formatDegrees(aircraft.trueTrackDeg) },
+        { label: 'Magnetic heading', value: formatDegrees(aircraft.magneticHeadingDeg) },
+        { label: 'Vertical rate', value: formatVerticalRate(aircraft) },
+        { label: 'On ground', value: formatOnGround(aircraft) },
+        { label: 'Category', value: aircraft.category ?? '-' },
+        { label: 'Origin', value: formatAirport(aircraft.origin) },
+        { label: 'Destination', value: formatAirport(aircraft.destination) },
+        { label: 'Last seen', value: `${formatAge(aircraft.lastSeenAt, nowMs)} ago` },
+    ];
+}

package/dist/format.d.ts

@@ -0,0 +1,91 @@
+import type { Aircraft } from '@squawk/types';
+import type { MessageLogEntry } from './aircraft-state.js';
+/**
+ * Whether `squawk` is one of the three universally-reserved emergency codes
+ * (hijack/radio failure/general emergency). Works identically across all
+ * three feed sources, since `squawk` is populated uniformly by JSON, SBS,
+ * and Beast.
+ *
+ * @param squawk - The aircraft's current squawk code, if known.
+ * @returns True if `squawk` is 7500, 7600, or 7700.
+ */
+export declare function isEmergencySquawk(squawk: string | undefined): boolean;
+/**
+ * Formats an aircraft's altitude for table display: barometric altitude
+ * preferred, geometric (GNSS) altitude as a fallback when barometric is
+ * unavailable. Does not special-case on-ground aircraft - see {@link formatOnGround}
+ * for that indicator.
+ *
+ * @param aircraft - The aircraft to read altitude from.
+ * @returns The altitude in feet with a unit suffix, or `"-"` if neither field is populated.
+ */
+export declare function formatAltitude(aircraft: Aircraft): string;
+/**
+ * Formats an aircraft's on-ground state for its own table column, separate
+ * from altitude. Deliberately blank (not e.g. "AIR") when airborne or
+ * unknown, so the column only draws attention when the indicator is true.
+ *
+ * @param aircraft - The aircraft to read on-ground status from.
+ * @returns `"GND"` if `onGround` is true, otherwise `"-"`.
+ */
+export declare function formatOnGround(aircraft: Aircraft): string;
+/**
+ * Formats an aircraft's heading for table display: true track preferred,
+ * magnetic heading as a fallback when true track is unavailable.
+ *
+ * @param aircraft - The aircraft to read heading from.
+ * @returns The heading in degrees with a trailing degree sign, or `"-"` if neither field is populated.
+ */
+export declare function formatHeading(aircraft: Aircraft): string;
+/**
+ * Formats an aircraft's ground speed for table display.
+ *
+ * @param aircraft - The aircraft to read ground speed from.
+ * @returns The ground speed in knots with a unit suffix, or `"-"` if unavailable.
+ */
+export declare function formatGroundSpeed(aircraft: Aircraft): string;
+/**
+ * Formats a great-circle distance for table display.
+ *
+ * @param distanceNm - Distance in nautical miles, or undefined if not computable.
+ * @returns The distance in nautical miles with a unit suffix, or `"-"` if undefined.
+ */
+export declare function formatDistance(distanceNm: number | undefined): string;
+/**
+ * Formats a great-circle bearing for table display, matching {@link formatHeading}'s style.
+ *
+ * @param bearingDeg - Bearing in degrees true, or undefined if not computable.
+ * @returns The bearing in degrees with a trailing degree sign, or `"-"` if undefined.
+ */
+export declare function formatBearing(bearingDeg: number | undefined): string;
+/**
+ * Formats an aircraft's vertical rate for table display, with an explicit
+ * `+` sign on climbs so climb/descend is visible without color.
+ *
+ * @param aircraft - The aircraft to read vertical rate from.
+ * @returns The vertical rate in feet per minute with a unit suffix, or `"-"` if unavailable.
+ */
+export declare function formatVerticalRate(aircraft: Aircraft): string;
+/**
+ * Formats the time elapsed since `lastSeenAt` for the table's age column,
+ * escalating precision as the value grows: seconds, then minutes/seconds,
+ * then hours/minutes.
+ *
+ * @param lastSeenAt - Unix epoch ms the aircraft was last updated.
+ * @param nowMs - Unix epoch ms to measure elapsed time against, supplied by the caller so this stays pure and testable.
+ * @returns A short elapsed-time string, e.g. `"3s"`, `"1m05s"`, or `"2h03m"`.
+ */
+export declare function formatAge(lastSeenAt: number, nowMs: number): string;
+/**
+ * Formats one {@link MessageLogEntry} for the `[M]essages` panel.
+ *
+ * The clock is rendered in UTC (`HH:MM:SS`) rather than local time so log
+ * output is deterministic in tests regardless of the runner's timezone -
+ * for a live-scrolling log the UTC/local distinction isn't meaningful to a
+ * user watching it update in real time.
+ *
+ * @param entry - The log entry to format.
+ * @returns A single display line, e.g. `"14:23:05  NEW   A0B1C2  UAL123"`.
+ */
+export declare function formatMessageLogLine(entry: MessageLogEntry): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAK3D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAErE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAGzD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAGxD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAQ7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAanE;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAKnE"}

package/dist/format.js

@@ -0,0 +1,138 @@
+/** Squawk codes that always indicate a declared emergency, regardless of source. */
+const EMERGENCY_SQUAWKS = new Set(['7500', '7600', '7700']);
+/**
+ * Whether `squawk` is one of the three universally-reserved emergency codes
+ * (hijack/radio failure/general emergency). Works identically across all
+ * three feed sources, since `squawk` is populated uniformly by JSON, SBS,
+ * and Beast.
+ *
+ * @param squawk - The aircraft's current squawk code, if known.
+ * @returns True if `squawk` is 7500, 7600, or 7700.
+ */
+export function isEmergencySquawk(squawk) {
+    return squawk !== undefined && EMERGENCY_SQUAWKS.has(squawk);
+}
+/**
+ * Formats an aircraft's altitude for table display: barometric altitude
+ * preferred, geometric (GNSS) altitude as a fallback when barometric is
+ * unavailable. Does not special-case on-ground aircraft - see {@link formatOnGround}
+ * for that indicator.
+ *
+ * @param aircraft - The aircraft to read altitude from.
+ * @returns The altitude in feet with a unit suffix, or `"-"` if neither field is populated.
+ */
+export function formatAltitude(aircraft) {
+    const altitudeFt = aircraft.position?.baroAltitudeFt ?? aircraft.position?.geoAltitudeFt;
+    return altitudeFt === undefined ? '-' : `${Math.round(altitudeFt)}ft`;
+}
+/**
+ * Formats an aircraft's on-ground state for its own table column, separate
+ * from altitude. Deliberately blank (not e.g. "AIR") when airborne or
+ * unknown, so the column only draws attention when the indicator is true.
+ *
+ * @param aircraft - The aircraft to read on-ground status from.
+ * @returns `"GND"` if `onGround` is true, otherwise `"-"`.
+ */
+export function formatOnGround(aircraft) {
+    return aircraft.onGround === true ? 'GND' : '-';
+}
+/**
+ * Formats an aircraft's heading for table display: true track preferred,
+ * magnetic heading as a fallback when true track is unavailable.
+ *
+ * @param aircraft - The aircraft to read heading from.
+ * @returns The heading in degrees with a trailing degree sign, or `"-"` if neither field is populated.
+ */
+export function formatHeading(aircraft) {
+    const headingDeg = aircraft.trueTrackDeg ?? aircraft.magneticHeadingDeg;
+    return headingDeg === undefined ? '-' : `${Math.round(headingDeg)}°`;
+}
+/**
+ * Formats an aircraft's ground speed for table display.
+ *
+ * @param aircraft - The aircraft to read ground speed from.
+ * @returns The ground speed in knots with a unit suffix, or `"-"` if unavailable.
+ */
+export function formatGroundSpeed(aircraft) {
+    return aircraft.groundSpeedKt === undefined ? '-' : `${Math.round(aircraft.groundSpeedKt)}kt`;
+}
+/**
+ * Formats a great-circle distance for table display.
+ *
+ * @param distanceNm - Distance in nautical miles, or undefined if not computable.
+ * @returns The distance in nautical miles with a unit suffix, or `"-"` if undefined.
+ */
+export function formatDistance(distanceNm) {
+    return distanceNm === undefined ? '-' : `${Math.round(distanceNm)}nm`;
+}
+/**
+ * Formats a great-circle bearing for table display, matching {@link formatHeading}'s style.
+ *
+ * @param bearingDeg - Bearing in degrees true, or undefined if not computable.
+ * @returns The bearing in degrees with a trailing degree sign, or `"-"` if undefined.
+ */
+export function formatBearing(bearingDeg) {
+    return bearingDeg === undefined ? '-' : `${Math.round(bearingDeg)}°`;
+}
+/**
+ * Formats an aircraft's vertical rate for table display, with an explicit
+ * `+` sign on climbs so climb/descend is visible without color.
+ *
+ * @param aircraft - The aircraft to read vertical rate from.
+ * @returns The vertical rate in feet per minute with a unit suffix, or `"-"` if unavailable.
+ */
+export function formatVerticalRate(aircraft) {
+    const rate = aircraft.verticalRateFtPerMin;
+    if (rate === undefined) {
+        return '-';
+    }
+    const rounded = Math.round(rate);
+    const sign = rounded > 0 ? '+' : '';
+    return `${sign}${rounded}fpm`;
+}
+/**
+ * Formats the time elapsed since `lastSeenAt` for the table's age column,
+ * escalating precision as the value grows: seconds, then minutes/seconds,
+ * then hours/minutes.
+ *
+ * @param lastSeenAt - Unix epoch ms the aircraft was last updated.
+ * @param nowMs - Unix epoch ms to measure elapsed time against, supplied by the caller so this stays pure and testable.
+ * @returns A short elapsed-time string, e.g. `"3s"`, `"1m05s"`, or `"2h03m"`.
+ */
+export function formatAge(lastSeenAt, nowMs) {
+    const elapsedSec = Math.max(0, Math.floor((nowMs - lastSeenAt) / 1000));
+    if (elapsedSec < 60) {
+        return `${elapsedSec}s`;
+    }
+    const minutes = Math.floor(elapsedSec / 60);
+    const seconds = elapsedSec % 60;
+    if (minutes < 60) {
+        return `${minutes}m${seconds.toString().padStart(2, '0')}s`;
+    }
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return `${hours}h${remainingMinutes.toString().padStart(2, '0')}m`;
+}
+/** Fixed-width label per {@link MessageLogEntry.type}, for column alignment in the messages panel. */
+const MESSAGE_LOG_LABELS = {
+    new: 'NEW ',
+    update: 'UPDT',
+    lost: 'LOST',
+};
+/**
+ * Formats one {@link MessageLogEntry} for the `[M]essages` panel.
+ *
+ * The clock is rendered in UTC (`HH:MM:SS`) rather than local time so log
+ * output is deterministic in tests regardless of the runner's timezone -
+ * for a live-scrolling log the UTC/local distinction isn't meaningful to a
+ * user watching it update in real time.
+ *
+ * @param entry - The log entry to format.
+ * @returns A single display line, e.g. `"14:23:05  NEW   A0B1C2  UAL123"`.
+ */
+export function formatMessageLogLine(entry) {
+    const time = new Date(entry.at).toISOString().slice(11, 19);
+    const label = MESSAGE_LOG_LABELS[entry.type];
+    const callsign = entry.callsign ?? '-';
+    return `${time}  ${label}  ${entry.icaoHex}  ${callsign}`;
+}

package/dist/location.d.ts

@@ -0,0 +1,20 @@
+import type { Aircraft, Coordinates } from '@squawk/types';
+/**
+ * Distance in nautical miles from a fixed observer `location` to `aircraft`'s
+ * current position, for the Dist column.
+ *
+ * @param location - The configured receiver location (`--lat`/`--lon`).
+ * @param aircraft - The aircraft to measure distance to.
+ * @returns The great-circle distance in nautical miles, or undefined if the aircraft has no position yet.
+ */
+export declare function distanceToAircraftNm(location: Coordinates, aircraft: Aircraft): number | undefined;
+/**
+ * Initial great-circle bearing in degrees true from a fixed observer
+ * `location` to `aircraft`'s current position, for the Brg column.
+ *
+ * @param location - The configured receiver location (`--lat`/`--lon`).
+ * @param aircraft - The aircraft to measure bearing to.
+ * @returns The bearing in degrees true (0-360), or undefined if the aircraft has no position yet.
+ */
+export declare function bearingToAircraftDeg(location: Coordinates, aircraft: Aircraft): number | undefined;
+//# sourceMappingURL=location.d.ts.map

package/dist/location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../src/location.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,EACrB,QAAQ,EAAE,QAAQ,GACjB,MAAM,GAAG,SAAS,CAKpB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,EACrB,QAAQ,EAAE,QAAQ,GACjB,MAAM,GAAG,SAAS,CAKpB"}

package/dist/location.js

@@ -0,0 +1,29 @@
+import { greatCircle } from '@squawk/geo';
+/**
+ * Distance in nautical miles from a fixed observer `location` to `aircraft`'s
+ * current position, for the Dist column.
+ *
+ * @param location - The configured receiver location (`--lat`/`--lon`).
+ * @param aircraft - The aircraft to measure distance to.
+ * @returns The great-circle distance in nautical miles, or undefined if the aircraft has no position yet.
+ */
+export function distanceToAircraftNm(location, aircraft) {
+    const position = aircraft.position;
+    return position === undefined
+        ? undefined
+        : greatCircle.distanceNm(location.lat, location.lon, position.lat, position.lon);
+}
+/**
+ * Initial great-circle bearing in degrees true from a fixed observer
+ * `location` to `aircraft`'s current position, for the Brg column.
+ *
+ * @param location - The configured receiver location (`--lat`/`--lon`).
+ * @param aircraft - The aircraft to measure bearing to.
+ * @returns The bearing in degrees true (0-360), or undefined if the aircraft has no position yet.
+ */
+export function bearingToAircraftDeg(location, aircraft) {
+    const position = aircraft.position;
+    return position === undefined
+        ? undefined
+        : greatCircle.bearing(location.lat, location.lon, position.lat, position.lon);
+}

package/dist/registration-cache.d.ts

@@ -0,0 +1,23 @@
+import type { IcaoRegistry } from '@squawk/icao-registry';
+import type { Aircraft, AircraftRegistration } from '@squawk/types';
+/**
+ * Per-`icaoHex` memoization cache for {@link enrichAircraftList} lookups.
+ * Stores `undefined` for a resolved miss too, so a hex with no registry
+ * match isn't looked up again on every render - an aircraft's registration
+ * never changes for the lifetime of a tracked session.
+ */
+export type RegistrationCache = Map<string, AircraftRegistration | undefined>;
+/**
+ * Returns a new array with each aircraft's `registration` field populated
+ * from `registry`, memoizing lookups in `cache` by `icaoHex` so a given hex
+ * is only resolved once regardless of how many times this runs. `adsb-feed`
+ * never populates `Aircraft.registration` itself, so this is adsbtop's own
+ * enrichment step, applied client-side after the feed's own normalization.
+ *
+ * @param aircraft - The aircraft to enrich, in any order.
+ * @param registry - The loaded registry to query, or undefined while it's still loading - aircraft pass through unchanged in that case.
+ * @param cache - Mutated in place with any newly-resolved lookups.
+ * @returns A new array; aircraft with no registry match keep their original (unmodified) object reference.
+ */
+export declare function enrichAircraftList(aircraft: readonly Aircraft[], registry: IcaoRegistry | undefined, cache: RegistrationCache): Aircraft[];
+//# sourceMappingURL=registration-cache.d.ts.map

package/dist/registration-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-cache.d.ts","sourceRoot":"","sources":["../src/registration-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAAC,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAC7B,QAAQ,EAAE,YAAY,GAAG,SAAS,EAClC,KAAK,EAAE,iBAAiB,GACvB,QAAQ,EAAE,CAWZ"}

package/dist/registration-cache.js

@@ -0,0 +1,24 @@
+/**
+ * Returns a new array with each aircraft's `registration` field populated
+ * from `registry`, memoizing lookups in `cache` by `icaoHex` so a given hex
+ * is only resolved once regardless of how many times this runs. `adsb-feed`
+ * never populates `Aircraft.registration` itself, so this is adsbtop's own
+ * enrichment step, applied client-side after the feed's own normalization.
+ *
+ * @param aircraft - The aircraft to enrich, in any order.
+ * @param registry - The loaded registry to query, or undefined while it's still loading - aircraft pass through unchanged in that case.
+ * @param cache - Mutated in place with any newly-resolved lookups.
+ * @returns A new array; aircraft with no registry match keep their original (unmodified) object reference.
+ */
+export function enrichAircraftList(aircraft, registry, cache) {
+    if (registry === undefined) {
+        return [...aircraft];
+    }
+    return aircraft.map((entry) => {
+        if (!cache.has(entry.icaoHex)) {
+            cache.set(entry.icaoHex, registry.lookup(entry.icaoHex));
+        }
+        const registration = cache.get(entry.icaoHex);
+        return registration === undefined ? entry : { ...entry, registration };
+    });
+}

package/dist/search.d.ts

@@ -0,0 +1,27 @@
+import type { Aircraft } from '@squawk/types';
+/**
+ * Whether `aircraft` matches `query` (case-insensitive substring match
+ * against ICAO hex, callsign, squawk, or N-number/registration). An empty or
+ * all-whitespace query never matches, so an unsubmitted search box selects
+ * nothing.
+ *
+ * @param aircraft - The aircraft to test.
+ * @param query - The search text.
+ * @returns True if `query` is a substring of the aircraft's hex, callsign, squawk, or registration.
+ */
+export declare function matchesSearch(aircraft: Aircraft, query: string): boolean;
+/**
+ * Finds the next aircraft matching `query`, searching from just after
+ * `currentIcaoHex` in `direction` and wrapping around the ends of `aircraft`.
+ * Used both for the initial search submit (searching forward from whatever
+ * row is currently selected) and for cycling to the next/previous match with
+ * `[N]`/`[Shift+N]`.
+ *
+ * @param aircraft - The currently displayed aircraft, in display order.
+ * @param query - The search text.
+ * @param currentIcaoHex - The currently selected aircraft's ICAO hex, or undefined if none is selected.
+ * @param direction - 1 to search forward (next match), -1 to search backward (previous match).
+ * @returns The ICAO hex of the next match, or undefined if `query` matches nothing.
+ */
+export declare function findMatchIcaoHex(aircraft: readonly Aircraft[], query: string, currentIcaoHex: string | undefined, direction: 1 | -1): string | undefined;
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAWxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAC7B,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC,GAChB,MAAM,GAAG,SAAS,CAwBpB"}

package/dist/search.js

@@ -0,0 +1,54 @@
+/**
+ * Whether `aircraft` matches `query` (case-insensitive substring match
+ * against ICAO hex, callsign, squawk, or N-number/registration). An empty or
+ * all-whitespace query never matches, so an unsubmitted search box selects
+ * nothing.
+ *
+ * @param aircraft - The aircraft to test.
+ * @param query - The search text.
+ * @returns True if `query` is a substring of the aircraft's hex, callsign, squawk, or registration.
+ */
+export function matchesSearch(aircraft, query) {
+    const normalized = query.trim().toLowerCase();
+    if (normalized === '') {
+        return false;
+    }
+    return (aircraft.icaoHex.toLowerCase().includes(normalized) ||
+        (aircraft.callsign?.toLowerCase().includes(normalized) ?? false) ||
+        (aircraft.squawk?.toLowerCase().includes(normalized) ?? false) ||
+        (aircraft.registration?.registration.toLowerCase().includes(normalized) ?? false));
+}
+/**
+ * Finds the next aircraft matching `query`, searching from just after
+ * `currentIcaoHex` in `direction` and wrapping around the ends of `aircraft`.
+ * Used both for the initial search submit (searching forward from whatever
+ * row is currently selected) and for cycling to the next/previous match with
+ * `[N]`/`[Shift+N]`.
+ *
+ * @param aircraft - The currently displayed aircraft, in display order.
+ * @param query - The search text.
+ * @param currentIcaoHex - The currently selected aircraft's ICAO hex, or undefined if none is selected.
+ * @param direction - 1 to search forward (next match), -1 to search backward (previous match).
+ * @returns The ICAO hex of the next match, or undefined if `query` matches nothing.
+ */
+export function findMatchIcaoHex(aircraft, query, currentIcaoHex, direction) {
+    const matchIndices = [];
+    aircraft.forEach((candidate, index) => {
+        if (matchesSearch(candidate, query)) {
+            matchIndices.push(index);
+        }
+    });
+    const firstMatchIndex = matchIndices[0];
+    const lastMatchIndex = matchIndices[matchIndices.length - 1];
+    if (firstMatchIndex === undefined || lastMatchIndex === undefined) {
+        return undefined;
+    }
+    const currentIndex = currentIcaoHex === undefined ? -1 : aircraft.findIndex((a) => a.icaoHex === currentIcaoHex);
+    if (direction === 1) {
+        const next = matchIndices.find((index) => index > currentIndex) ?? firstMatchIndex;
+        return aircraft[next]?.icaoHex;
+    }
+    const reversedMatches = [...matchIndices].reverse();
+    const previous = reversedMatches.find((index) => index < currentIndex) ?? lastMatchIndex;
+    return aircraft[previous]?.icaoHex;
+}