@squawk/mode-s 0.1.0

package/dist/comm-b.js

@@ -0,0 +1,245 @@
+import { extractBits } from './bits.js';
+/**
+ * Combines an unsigned magnitude and a separate sign bit into a signed
+ * value. Mode-S encodes sign and magnitude as separate bit fields (not
+ * two's complement) - sign=1, magnitude=0 represents `-2**width`, not `-0`.
+ */
+function signed(value, width, sign) {
+    return sign === 1 ? value - (1 << width) : value;
+}
+/** Wraps an angle into the half-open interval [0, 360) - JavaScript's `%` follows the dividend's sign for negative input, unlike the floor-mod this needs. */
+function normalizeAngleDeg(deg) {
+    return ((deg % 360) + 360) % 360;
+}
+/**
+ * Returns true if a status-gated value field is inconsistent: BDS registers
+ * with status-bit gates encode each field as a status bit followed by a
+ * fixed-width value, and when the status is 0 the entire value field
+ * (including any sign bit) must also be 0. A nonzero value with status=0
+ * indicates either a corrupt message or a different BDS register's payload
+ * accidentally passing this one's checks.
+ */
+function wrongStatus(mb, statusBit, valueStart, valueWidth) {
+    if (extractBits(mb, statusBit, 1) !== 0) {
+        return false;
+    }
+    return extractBits(mb, valueStart, valueWidth) !== 0;
+}
+function decodeTargetAltitudeSource(raw) {
+    switch (raw) {
+        case 1:
+            return 'aircraftAltitude';
+        case 2:
+            return 'mcpFcu';
+        case 3:
+            return 'fms';
+        default:
+            return 'unknown';
+    }
+}
+/** Whether `mb` is a structurally plausible BDS 4,0 (Selected Vertical Intention) register - status-bit/value consistency and reserved-bits-must-be-zero checks. Has no format-identifier byte, so this is a heuristic, not a certainty. */
+function isSelectedVerticalIntention(mb) {
+    if (mb.every((byte) => byte === 0)) {
+        return false;
+    }
+    if (wrongStatus(mb, 0, 1, 12)) {
+        return false;
+    }
+    if (wrongStatus(mb, 13, 14, 12)) {
+        return false;
+    }
+    if (wrongStatus(mb, 26, 27, 12)) {
+        return false;
+    }
+    if (wrongStatus(mb, 47, 48, 3)) {
+        return false;
+    }
+    if (wrongStatus(mb, 53, 54, 2)) {
+        return false;
+    }
+    if (extractBits(mb, 39, 8) !== 0) {
+        return false;
+    }
+    return extractBits(mb, 51, 2) === 0;
+}
+/**
+ * Decodes a BDS 4,0 (Selected Vertical Intention) register.
+ *
+ * @param mb - The 7-byte MB field of a DF20/21 Comm-B reply, already known (or inferred via {@link inferCommBRegisters}) to be BDS 4,0.
+ * @returns The decoded selected vertical intention.
+ */
+export function decodeSelectedVerticalIntention(mb) {
+    const mcpStatus = extractBits(mb, 0, 1);
+    const fmsStatus = extractBits(mb, 13, 1);
+    const baroStatus = extractBits(mb, 26, 1);
+    const modeStatus = extractBits(mb, 47, 1);
+    const sourceStatus = extractBits(mb, 53, 1);
+    return {
+        bdsCode: '4,0',
+        mcpFcuSelectedAltitudeFt: mcpStatus === 1 ? extractBits(mb, 1, 12) * 16 : undefined,
+        fmsSelectedAltitudeFt: fmsStatus === 1 ? extractBits(mb, 14, 12) * 16 : undefined,
+        baroPressureSettingMb: baroStatus === 1 ? extractBits(mb, 27, 12) * 0.1 + 800 : undefined,
+        vnavModeActive: modeStatus === 1 ? extractBits(mb, 48, 1) === 1 : undefined,
+        altitudeHoldModeActive: modeStatus === 1 ? extractBits(mb, 49, 1) === 1 : undefined,
+        approachModeActive: modeStatus === 1 ? extractBits(mb, 50, 1) === 1 : undefined,
+        targetAltitudeSource: sourceStatus === 1 ? decodeTargetAltitudeSource(extractBits(mb, 54, 2)) : undefined,
+    };
+}
+/** Whether `mb` is a structurally plausible BDS 5,0 (Track and Turn Report) register - status-bit consistency plus physically-plausible range checks (e.g. |roll| <= 35deg). Has no format-identifier byte, so this is a heuristic, not a certainty - a payload can pass both this and {@link isHeadingAndSpeedReport}. */
+function isTrackAndTurnReport(mb) {
+    if (mb.every((byte) => byte === 0)) {
+        return false;
+    }
+    if (wrongStatus(mb, 0, 1, 10)) {
+        return false;
+    }
+    if (wrongStatus(mb, 11, 12, 11)) {
+        return false;
+    }
+    if (wrongStatus(mb, 23, 24, 10)) {
+        return false;
+    }
+    if (wrongStatus(mb, 34, 35, 10)) {
+        return false;
+    }
+    if (wrongStatus(mb, 45, 46, 10)) {
+        return false;
+    }
+    if (extractBits(mb, 0, 1) === 1) {
+        const rollDeg = (signed(extractBits(mb, 2, 9), 9, extractBits(mb, 1, 1)) * 45) / 256;
+        if (Math.abs(rollDeg) > 35) {
+            return false;
+        }
+    }
+    const gsStatus = extractBits(mb, 23, 1);
+    const gsRaw = extractBits(mb, 24, 10);
+    if (gsStatus === 1 && gsRaw * 2 > 600) {
+        return false;
+    }
+    const tasStatus = extractBits(mb, 45, 1);
+    const tasRaw = extractBits(mb, 46, 10);
+    if (tasStatus === 1 && tasRaw * 2 > 600) {
+        return false;
+    }
+    return !(gsStatus === 1 && tasStatus === 1 && Math.abs(tasRaw * 2 - gsRaw * 2) > 200);
+}
+/**
+ * Decodes a BDS 5,0 (Track and Turn Report) register.
+ *
+ * @param mb - The 7-byte MB field of a DF20/21 Comm-B reply, already known (or inferred via {@link inferCommBRegisters}) to be BDS 5,0.
+ * @returns The decoded track and turn report.
+ */
+export function decodeTrackAndTurnReport(mb) {
+    const rollStatus = extractBits(mb, 0, 1);
+    const trackStatus = extractBits(mb, 11, 1);
+    const gsStatus = extractBits(mb, 23, 1);
+    const trackRateStatus = extractBits(mb, 34, 1);
+    const tasStatus = extractBits(mb, 45, 1);
+    return {
+        bdsCode: '5,0',
+        rollAngleDeg: rollStatus === 1
+            ? (signed(extractBits(mb, 2, 9), 9, extractBits(mb, 1, 1)) * 45) / 256
+            : undefined,
+        trueTrackDeg: trackStatus === 1
+            ? normalizeAngleDeg((signed(extractBits(mb, 13, 10), 10, extractBits(mb, 12, 1)) * 90) / 512)
+            : undefined,
+        groundSpeedKt: gsStatus === 1 ? extractBits(mb, 24, 10) * 2 : undefined,
+        trackAngleRateDegPerSec: trackRateStatus === 1
+            ? (signed(extractBits(mb, 36, 9), 9, extractBits(mb, 35, 1)) * 8) / 256
+            : undefined,
+        trueAirspeedKt: tasStatus === 1 ? extractBits(mb, 46, 10) * 2 : undefined,
+    };
+}
+/** Whether `mb` is a structurally plausible BDS 6,0 (Heading and Speed Report) register - status-bit consistency plus physically-plausible range checks (e.g. Mach <= 1). Has no format-identifier byte, so this is a heuristic, not a certainty - a payload can pass both this and {@link isTrackAndTurnReport}. */
+function isHeadingAndSpeedReport(mb) {
+    if (mb.every((byte) => byte === 0)) {
+        return false;
+    }
+    if (wrongStatus(mb, 0, 1, 11)) {
+        return false;
+    }
+    if (wrongStatus(mb, 12, 13, 10)) {
+        return false;
+    }
+    if (wrongStatus(mb, 23, 24, 10)) {
+        return false;
+    }
+    if (wrongStatus(mb, 34, 35, 10)) {
+        return false;
+    }
+    if (wrongStatus(mb, 45, 46, 10)) {
+        return false;
+    }
+    const iasStatus = extractBits(mb, 12, 1);
+    if (iasStatus === 1 && extractBits(mb, 13, 10) > 500) {
+        return false;
+    }
+    const machStatus = extractBits(mb, 23, 1);
+    if (machStatus === 1 && (extractBits(mb, 24, 10) * 2.048) / 512 > 1) {
+        return false;
+    }
+    const vrbStatus = extractBits(mb, 34, 1);
+    if (vrbStatus === 1) {
+        const vrb = signed(extractBits(mb, 36, 9), 9, extractBits(mb, 35, 1)) * 32;
+        if (Math.abs(vrb) > 6000) {
+            return false;
+        }
+    }
+    const vriStatus = extractBits(mb, 45, 1);
+    if (vriStatus === 1) {
+        const vri = signed(extractBits(mb, 47, 9), 9, extractBits(mb, 46, 1)) * 32;
+        if (Math.abs(vri) > 6000) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Decodes a BDS 6,0 (Heading and Speed Report) register.
+ *
+ * @param mb - The 7-byte MB field of a DF20/21 Comm-B reply, already known (or inferred via {@link inferCommBRegisters}) to be BDS 6,0.
+ * @returns The decoded heading and speed report.
+ */
+export function decodeHeadingAndSpeedReport(mb) {
+    const headingStatus = extractBits(mb, 0, 1);
+    const iasStatus = extractBits(mb, 12, 1);
+    const machStatus = extractBits(mb, 23, 1);
+    const vrbStatus = extractBits(mb, 34, 1);
+    const vriStatus = extractBits(mb, 45, 1);
+    return {
+        bdsCode: '6,0',
+        magneticHeadingDeg: headingStatus === 1
+            ? normalizeAngleDeg((signed(extractBits(mb, 2, 10), 10, extractBits(mb, 1, 1)) * 90) / 512)
+            : undefined,
+        indicatedAirspeedKt: iasStatus === 1 ? extractBits(mb, 13, 10) : undefined,
+        mach: machStatus === 1 ? (extractBits(mb, 24, 10) * 2.048) / 512 : undefined,
+        baroVerticalRateFtPerMin: vrbStatus === 1 ? signed(extractBits(mb, 36, 9), 9, extractBits(mb, 35, 1)) * 32 : undefined,
+        inertialVerticalRateFtPerMin: vriStatus === 1 ? signed(extractBits(mb, 47, 9), 9, extractBits(mb, 46, 1)) * 32 : undefined,
+    };
+}
+/**
+ * Infers which "Enhanced Surveillance" Comm-B register(s) a DF20/21 MB
+ * field plausibly holds, and decodes each. Unlike DF17/18's type-code-coded
+ * ME field, a Comm-B MB field carries no self-declared register identifier
+ * for BDS 4,0/5,0/6,0 - this package would rather report every plausible
+ * candidate (via structural and range validation, matching pyModeS's own
+ * approach to this exact ambiguity) than silently guess a single wrong
+ * answer. In practice this is usually unambiguous; BDS 5,0 and 6,0 are the
+ * pair most likely to both pass validation for the same bytes.
+ *
+ * @param mb - The 7-byte MB field of a DF20/21 Comm-B reply.
+ * @returns Every register this MB field plausibly holds - empty if none, one if unambiguous, more than one if genuinely ambiguous.
+ */
+export function inferCommBRegisters(mb) {
+    const candidates = [];
+    if (isSelectedVerticalIntention(mb)) {
+        candidates.push(decodeSelectedVerticalIntention(mb));
+    }
+    if (isTrackAndTurnReport(mb)) {
+        candidates.push(decodeTrackAndTurnReport(mb));
+    }
+    if (isHeadingAndSpeedReport(mb)) {
+        candidates.push(decodeHeadingAndSpeedReport(mb));
+    }
+    return candidates;
+}

package/dist/cpr.d.ts

@@ -0,0 +1,71 @@
+import type { Position } from '@squawk/types';
+import type { CprPosition, CprReference } from './types/index.js';
+/**
+ * Returns the number of CPR longitude zones (NL) at a given latitude, per
+ * ICAO Annex 10 Vol. IV / RTCA DO-260B SS A.1.7.2. NL is 1-59, monotone
+ * non-increasing in absolute latitude: 59 at the equator, 2 at +-87 deg, 1
+ * beyond +-87 deg.
+ *
+ * @param latDeg - Latitude in decimal degrees.
+ * @returns The number of longitude zones, 1-59.
+ */
+export declare function cprNumLongitudeZones(latDeg: number): number;
+/**
+ * Resolves an absolute position from a paired even and odd airborne CPR
+ * frame (ADS-B BDS 0,5 / 2,0 - type codes 9-18 and 20-22), per DO-260B SS
+ * A.1.7.3. The two frames must be close enough in time that the aircraft
+ * could not have crossed a latitude zone boundary - in practice, no more
+ * than about 10 seconds apart, since airborne position is broadcast at
+ * roughly 2 Hz. Enforcing that window is the caller's responsibility; this
+ * function only performs a zone-consistency check as a lightweight guard,
+ * which cannot by itself detect a same-zone false positive from a pair
+ * spanning too wide a gap.
+ *
+ * @param even - Raw CPR fields from the even-format (F=0) frame.
+ * @param odd - Raw CPR fields from the odd-format (F=1) frame.
+ * @param newerFormat - Which frame is more recent - determines which frame's latitude zone the result is reported in.
+ * @returns The resolved position, or undefined if the two frames fall in different latitude zones (the pair cannot be combined) or the result is physically impossible.
+ */
+export declare function decodeAirborneCprPair(even: CprPosition, odd: CprPosition, newerFormat: 'even' | 'odd'): Position | undefined;
+/**
+ * Resolves an absolute position from a single airborne CPR frame plus a
+ * known nearby reference position, per DO-260B SS A.1.7.5. The reference
+ * must be within roughly 180 NM of the true position - typically the
+ * aircraft's own last known position, or the receiver's location as a
+ * fallback for the first message from a new aircraft.
+ *
+ * @param format - Whether `frame` is an even (F=0) or odd (F=1) format frame.
+ * @param frame - Raw CPR fields from the frame.
+ * @param reference - A position known to be near the frame's true position.
+ * @returns The resolved position.
+ */
+export declare function decodeAirborneCprWithReference(format: 'even' | 'odd', frame: CprPosition, reference: CprReference): Position;
+/**
+ * Resolves an absolute position from a paired even and odd surface CPR
+ * frame (ADS-B BDS 0,6 - type codes 5-8), per DO-260B SS A.1.7.4. Surface
+ * CPR spans a 90 degree latitude zone (versus 360 degree for airborne) and
+ * is ambiguous across four longitude quadrants, so unlike the airborne
+ * pair decode, a reference position is required to resolve the correct
+ * hemisphere and quadrant - the receiver's own location is normally used.
+ *
+ * @param even - Raw CPR fields from the even-format frame.
+ * @param odd - Raw CPR fields from the odd-format frame.
+ * @param newerFormat - Which frame is more recent.
+ * @param reference - A position known to be within about 45 NM of the true position (typically the receiver's location).
+ * @returns The resolved position, or undefined if the two frames fall in different latitude zones.
+ */
+export declare function decodeSurfaceCprPair(even: CprPosition, odd: CprPosition, newerFormat: 'even' | 'odd', reference: CprReference): Position | undefined;
+/**
+ * Resolves an absolute position from a single surface CPR frame plus a
+ * known nearby reference position, per DO-260B SS A.1.7.6. The reference
+ * must be within roughly 45 NM of the true position - typically the
+ * receiver's own location, since surface traffic is by definition close to
+ * an airport the receiver can see.
+ *
+ * @param format - Whether `frame` is an even (F=0) or odd (F=1) format frame.
+ * @param frame - Raw CPR fields from the frame.
+ * @param reference - A position known to be near the frame's true position.
+ * @returns The resolved position.
+ */
+export declare function decodeSurfaceCprWithReference(format: 'even' | 'odd', frame: CprPosition, reference: CprReference): Position;
+//# sourceMappingURL=cpr.d.ts.map

package/dist/cpr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpr.d.ts","sourceRoot":"","sources":["../src/cpr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAuClE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAU3D;AA6DD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,MAAM,GAAG,KAAK,GAC1B,QAAQ,GAAG,SAAS,CAuCtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,MAAM,GAAG,KAAK,EACtB,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,YAAY,GACtB,QAAQ,CAEV;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,MAAM,GAAG,KAAK,EAC3B,SAAS,EAAE,YAAY,GACtB,QAAQ,GAAG,SAAS,CA4CtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,GAAG,KAAK,EACtB,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,YAAY,GACtB,QAAQ,CAEV"}

package/dist/cpr.js

@@ -0,0 +1,220 @@
+/** Raw CPR fields are 17-bit, normalized to [0, 1) by dividing by 2^17. */
+const CPR_DENOMINATOR = 131072;
+/**
+ * Latitude boundaries (absolute degrees, ascending) where the number of CPR
+ * longitude zones (NL) steps down by one. Entry `i` is the latitude at
+ * which NL transitions from `59 - i` to `59 - i - 1`. Derived once from the
+ * closed-form NL(lat) trigonometric expression in ICAO Annex 10 Vol. IV /
+ * RTCA DO-260B SS A.1.7.2 with the fixed `nz = 15` zone count - stable
+ * across releases since the formula has no other free parameters. A static
+ * table avoids repeated trig evaluation on every position decode.
+ */
+const NL_BOUNDARIES = [
+    10.47047129996848, 14.828174368686794, 18.186263570713354, 21.029394926028463, 23.545044865570706,
+    25.829247070587755, 27.938987101219045, 29.911356857318083, 31.77209707681077, 33.53993436298484,
+    35.22899597796385, 36.85025107593526, 38.41241892412256, 39.922566843338615, 41.38651832260239,
+    42.80914012243555, 44.194549514192744, 45.546267226602346, 46.867332524987454, 48.160391280966216,
+    49.42776439255687, 50.67150165553835, 51.893424691687684, 53.09516152796003, 54.278174722729,
+    55.44378444495043, 56.59318756205918, 57.72747353866114, 58.84763776148457, 59.954592766940294,
+    61.04917774246351, 62.13216659210329, 63.20427479381928, 64.2661652256744, 65.31845309682089,
+    66.36171008382617, 67.39646774084667, 68.4232202208333, 69.44242631144024, 70.454510749876,
+    71.45986473028982, 72.45884544728945, 73.45177441667865, 74.43893415725137, 75.42056256653356,
+    76.39684390794469, 77.36789461328188, 78.33374082922747, 79.29428225456925, 80.24923213280512,
+    81.19801349271948, 82.13956980510606, 83.07199444719814, 83.99173562980565, 84.89166190702085,
+    85.75541620944418, 86.535369975121, 87.0,
+];
+/** True modulo (JS `%` can return a negative result; CPR math requires the mathematical modulo). */
+function mod(a, b) {
+    return ((a % b) + b) % b;
+}
+/** Wraps a longitude in degrees into the canonical [-180, 180) range. Longitude is circular, so a raw interpolated value outside that range (e.g. 180.5) represents a valid position (-179.5), not an error. */
+function normalizeLongitudeDeg(lonDeg) {
+    return mod(lonDeg + 180, 360) - 180;
+}
+/**
+ * Returns the number of CPR longitude zones (NL) at a given latitude, per
+ * ICAO Annex 10 Vol. IV / RTCA DO-260B SS A.1.7.2. NL is 1-59, monotone
+ * non-increasing in absolute latitude: 59 at the equator, 2 at +-87 deg, 1
+ * beyond +-87 deg.
+ *
+ * @param latDeg - Latitude in decimal degrees.
+ * @returns The number of longitude zones, 1-59.
+ */
+export function cprNumLongitudeZones(latDeg) {
+    const absLat = Math.abs(latDeg);
+    if (absLat > 87) {
+        return 1;
+    }
+    if (absLat === 87) {
+        return 2;
+    }
+    const idx = NL_BOUNDARIES.findIndex((boundary) => boundary > absLat);
+    return 59 - idx;
+}
+/**
+ * Shared core of the even/odd pair decoders: checks the two frames land in
+ * consistent NL zones, then interpolates the longitude fraction within
+ * `latSpanDeg` (360 for airborne, 90 for surface). Both pair decoders
+ * resolve latitude differently before calling this (surface needs an extra
+ * hemisphere disambiguation step airborne doesn't), but the zone-check and
+ * longitude interpolation that follows is identical modulo the span.
+ */
+function resolveCprPairLongitude(latSpanDeg, latEven, latOdd, cprLonEven, cprLonOdd, newerFormat) {
+    const nlEven = cprNumLongitudeZones(latEven);
+    const nlOdd = cprNumLongitudeZones(latOdd);
+    if (nlEven !== nlOdd) {
+        return undefined;
+    }
+    const lat = newerFormat === 'even' ? latEven : latOdd;
+    const nl = newerFormat === 'even' ? nlEven : nlOdd;
+    const ni = newerFormat === 'even' ? Math.max(nl, 1) : Math.max(nl - 1, 1);
+    const m = Math.floor(cprLonEven * (nl - 1) - cprLonOdd * nl + 0.5);
+    const cprLonForFormat = newerFormat === 'even' ? cprLonEven : cprLonOdd;
+    const lonFraction = (latSpanDeg / ni) * (mod(m, ni) + cprLonForFormat);
+    return { lat, lonFraction };
+}
+/**
+ * Shared core of the single-frame-plus-reference decoders: resolves
+ * latitude and longitude within `latSpanDeg` (360 for airborne, 90 for
+ * surface) against a known nearby reference position.
+ */
+function decodeCprWithReference(latSpanDeg, format, frame, reference) {
+    const cprLat = frame.latCpr / CPR_DENOMINATOR;
+    const cprLon = frame.lonCpr / CPR_DENOMINATOR;
+    const dLat = format === 'odd' ? latSpanDeg / 59 : latSpanDeg / 60;
+    const j = Math.floor(0.5 + reference.lat / dLat - cprLat);
+    const lat = dLat * (j + cprLat);
+    const ni = cprNumLongitudeZones(lat) - (format === 'odd' ? 1 : 0);
+    const dLon = ni > 0 ? latSpanDeg / ni : latSpanDeg;
+    const m = Math.floor(0.5 + reference.lon / dLon - cprLon);
+    const lon = normalizeLongitudeDeg(dLon * (m + cprLon));
+    return { lat, lon };
+}
+/**
+ * Resolves an absolute position from a paired even and odd airborne CPR
+ * frame (ADS-B BDS 0,5 / 2,0 - type codes 9-18 and 20-22), per DO-260B SS
+ * A.1.7.3. The two frames must be close enough in time that the aircraft
+ * could not have crossed a latitude zone boundary - in practice, no more
+ * than about 10 seconds apart, since airborne position is broadcast at
+ * roughly 2 Hz. Enforcing that window is the caller's responsibility; this
+ * function only performs a zone-consistency check as a lightweight guard,
+ * which cannot by itself detect a same-zone false positive from a pair
+ * spanning too wide a gap.
+ *
+ * @param even - Raw CPR fields from the even-format (F=0) frame.
+ * @param odd - Raw CPR fields from the odd-format (F=1) frame.
+ * @param newerFormat - Which frame is more recent - determines which frame's latitude zone the result is reported in.
+ * @returns The resolved position, or undefined if the two frames fall in different latitude zones (the pair cannot be combined) or the result is physically impossible.
+ */
+export function decodeAirborneCprPair(even, odd, newerFormat) {
+    const cprLatEven = even.latCpr / CPR_DENOMINATOR;
+    const cprLonEven = even.lonCpr / CPR_DENOMINATOR;
+    const cprLatOdd = odd.latCpr / CPR_DENOMINATOR;
+    const cprLonOdd = odd.lonCpr / CPR_DENOMINATOR;
+    const j = Math.floor(59 * cprLatEven - 60 * cprLatOdd + 0.5);
+    let latEven = (360 / 60) * (mod(j, 60) + cprLatEven);
+    let latOdd = (360 / 59) * (mod(j, 59) + cprLatOdd);
+    if (latEven >= 270) {
+        latEven -= 360;
+    }
+    if (latOdd >= 270) {
+        latOdd -= 360;
+    }
+    const resolved = resolveCprPairLongitude(360, latEven, latOdd, cprLonEven, cprLonOdd, newerFormat);
+    if (resolved === undefined) {
+        return undefined;
+    }
+    // A frame pair that passes the zone-consistency check above but still
+    // produces an out-of-range latitude is a straddling-boundary false
+    // positive - reject rather than report a physically impossible
+    // position. Longitude has no equivalent failure mode: the interpolation
+    // formula is bounded to one span by construction, and
+    // normalizeLongitudeDeg always yields a valid [-180, 180) result.
+    if (Math.abs(resolved.lat) > 90) {
+        return undefined;
+    }
+    return { lat: resolved.lat, lon: normalizeLongitudeDeg(resolved.lonFraction) };
+}
+/**
+ * Resolves an absolute position from a single airborne CPR frame plus a
+ * known nearby reference position, per DO-260B SS A.1.7.5. The reference
+ * must be within roughly 180 NM of the true position - typically the
+ * aircraft's own last known position, or the receiver's location as a
+ * fallback for the first message from a new aircraft.
+ *
+ * @param format - Whether `frame` is an even (F=0) or odd (F=1) format frame.
+ * @param frame - Raw CPR fields from the frame.
+ * @param reference - A position known to be near the frame's true position.
+ * @returns The resolved position.
+ */
+export function decodeAirborneCprWithReference(format, frame, reference) {
+    return decodeCprWithReference(360, format, frame, reference);
+}
+/**
+ * Resolves an absolute position from a paired even and odd surface CPR
+ * frame (ADS-B BDS 0,6 - type codes 5-8), per DO-260B SS A.1.7.4. Surface
+ * CPR spans a 90 degree latitude zone (versus 360 degree for airborne) and
+ * is ambiguous across four longitude quadrants, so unlike the airborne
+ * pair decode, a reference position is required to resolve the correct
+ * hemisphere and quadrant - the receiver's own location is normally used.
+ *
+ * @param even - Raw CPR fields from the even-format frame.
+ * @param odd - Raw CPR fields from the odd-format frame.
+ * @param newerFormat - Which frame is more recent.
+ * @param reference - A position known to be within about 45 NM of the true position (typically the receiver's location).
+ * @returns The resolved position, or undefined if the two frames fall in different latitude zones.
+ */
+export function decodeSurfaceCprPair(even, odd, newerFormat, reference) {
+    const cprLatEven = even.latCpr / CPR_DENOMINATOR;
+    const cprLonEven = even.lonCpr / CPR_DENOMINATOR;
+    const cprLatOdd = odd.latCpr / CPR_DENOMINATOR;
+    const cprLonOdd = odd.lonCpr / CPR_DENOMINATOR;
+    const j = Math.floor(59 * cprLatEven - 60 * cprLatOdd + 0.5);
+    const latEvenNorth = (90 / 60) * (mod(j, 60) + cprLatEven);
+    const latOddNorth = (90 / 59) * (mod(j, 59) + cprLatOdd);
+    const latEvenSouth = latEvenNorth - 90;
+    const latOddSouth = latOddNorth - 90;
+    // Surface CPR is ambiguous over two 90 degree latitude zones (north and
+    // south of the equator) - resolve using whichever zone's newer-frame
+    // latitude lands closer to the reference, rather than the reference's own
+    // hemisphere (a receiver and aircraft can be on opposite sides of the
+    // equator while still satisfying the 45 NM limit).
+    const newerLatNorth = newerFormat === 'even' ? latEvenNorth : latOddNorth;
+    const newerLatSouth = newerFormat === 'even' ? latEvenSouth : latOddSouth;
+    const useNorth = Math.abs(reference.lat - newerLatNorth) <= Math.abs(reference.lat - newerLatSouth);
+    const latEven = useNorth ? latEvenNorth : latEvenSouth;
+    const latOdd = useNorth ? latOddNorth : latOddSouth;
+    const resolved = resolveCprPairLongitude(90, latEven, latOdd, cprLonEven, cprLonOdd, newerFormat);
+    if (resolved === undefined) {
+        return undefined;
+    }
+    // Surface longitude only narrows to one of four 90 degree quadrants -
+    // pick whichever wraps closest to the reference, treating longitude as
+    // circular (near the date line, -180 is one degree from +179, not 359).
+    let bestLon = resolved.lonFraction;
+    let bestLonDiff = Number.POSITIVE_INFINITY;
+    for (const quadrantOffset of [0, 90, 180, 270]) {
+        const candidateLon = normalizeLongitudeDeg(resolved.lonFraction + quadrantOffset);
+        const diff = Math.abs(normalizeLongitudeDeg(candidateLon - reference.lon));
+        if (diff < bestLonDiff) {
+            bestLonDiff = diff;
+            bestLon = candidateLon;
+        }
+    }
+    return { lat: resolved.lat, lon: bestLon };
+}
+/**
+ * Resolves an absolute position from a single surface CPR frame plus a
+ * known nearby reference position, per DO-260B SS A.1.7.6. The reference
+ * must be within roughly 45 NM of the true position - typically the
+ * receiver's own location, since surface traffic is by definition close to
+ * an airport the receiver can see.
+ *
+ * @param format - Whether `frame` is an even (F=0) or odd (F=1) format frame.
+ * @param frame - Raw CPR fields from the frame.
+ * @param reference - A position known to be near the frame's true position.
+ * @returns The resolved position.
+ */
+export function decodeSurfaceCprWithReference(format, frame, reference) {
+    return decodeCprWithReference(90, format, frame, reference);
+}

package/dist/emergency-status.d.ts

@@ -0,0 +1,10 @@
+import type { EmergencyState } from './types/index.js';
+/**
+ * Decodes the 3-bit emergency state field of an ADS-B aircraft status
+ * message (BDS 6,1 subtype 1, type code 28).
+ *
+ * @param rawState - The raw 3-bit field, 0-7.
+ * @returns The decoded emergency state.
+ */
+export declare function decodeEmergencyState(rawState: number): EmergencyState;
+//# sourceMappingURL=emergency-status.d.ts.map

package/dist/emergency-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emergency-status.d.ts","sourceRoot":"","sources":["../src/emergency-status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAcvD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAErE"}

package/dist/emergency-status.js

@@ -0,0 +1,21 @@
+/** 3-bit emergency state field values, per ICAO Annex 10 Vol. IV / RTCA DO-260. */
+const EMERGENCY_STATES = [
+    'none',
+    'general',
+    'lifeguardMedical',
+    'minimumFuel',
+    'noCommunications',
+    'unlawfulInterference',
+    'downed',
+    'reserved',
+];
+/**
+ * Decodes the 3-bit emergency state field of an ADS-B aircraft status
+ * message (BDS 6,1 subtype 1, type code 28).
+ *
+ * @param rawState - The raw 3-bit field, 0-7.
+ * @returns The decoded emergency state.
+ */
+export function decodeEmergencyState(rawState) {
+    return EMERGENCY_STATES[rawState] ?? 'reserved';
+}

package/dist/frame.d.ts

@@ -0,0 +1,42 @@
+import type { ModeSMessageEnvelope } from './types/index.js';
+/**
+ * Extracts the downlink format from a Mode-S message's first 5 bits.
+ *
+ * @param bytes - Raw message bytes (7 or 14 bytes).
+ * @returns The raw downlink format value, 0-31.
+ */
+export declare function extractDownlinkFormat(bytes: Uint8Array): number;
+/**
+ * Computes the 24-bit Mode-S CRC remainder over an entire message (all
+ * bytes, including the trailing 24-bit parity field), via the standard
+ * bit-serial polynomial division used to check or recover Mode-S CRCs.
+ *
+ * See {@link ModeSMessageEnvelope.crcRemainder} for how to interpret the
+ * result - it is a pass/fail check for squitter formats (DF11/17/18) but a
+ * recovered ICAO address for surveillance-reply formats.
+ *
+ * @param bytes - Raw message bytes (7 or 14 bytes), parity field included.
+ * @returns The 24-bit CRC remainder.
+ */
+export declare function computeCrc24(bytes: Uint8Array): number;
+/**
+ * Parses the shared envelope (downlink format, CRC remainder) out of a raw
+ * Mode-S message. {@link decodeModeSMessage} uses this to decide how to
+ * route a message before calling the per-type decoders - those decoders
+ * take a raw ME field or an already-extracted field value, not the
+ * envelope itself.
+ *
+ * ```typescript
+ * import { parseModeSFrame } from '@squawk/mode-s';
+ *
+ * const envelope = parseModeSFrame(rawMessageBytes);
+ * if (envelope.downlinkFormat === 17 && envelope.crcRemainder === 0) {
+ *   // unmodified DF17 extended squitter, safe to decode further
+ * }
+ * ```
+ *
+ * @param bytes - Raw message bytes (7 or 14 bytes).
+ * @returns The parsed envelope.
+ */
+export declare function parseModeSFrame(bytes: Uint8Array): ModeSMessageEnvelope;
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAS7D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAG/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAatD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,oBAAoB,CAMvE"}