@squawk/mode-s 0.1.0

package/dist/frame.js

@@ -0,0 +1,68 @@
+/**
+ * The 24-bit Mode-S CRC generator polynomial (ICAO Annex 10 Vol. IV / RTCA
+ * DO-260), represented as its low 24 bits - the implicit leading term
+ * cancels against the overflow bit it is XORed in response to.
+ */
+const CRC24_GENERATOR = 0xfff409;
+/**
+ * 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 function extractDownlinkFormat(bytes) {
+    const first = bytes[0] ?? 0;
+    return first >> 3;
+}
+/**
+ * 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 function computeCrc24(bytes) {
+    let register = 0;
+    for (const byte of bytes) {
+        for (let bitIndex = 7; bitIndex >= 0; bitIndex--) {
+            const bit = (byte >> bitIndex) & 1;
+            const topBit = (register >> 23) & 1;
+            register = ((register << 1) | bit) & 0xffffff;
+            if (topBit === 1) {
+                register ^= CRC24_GENERATOR;
+            }
+        }
+    }
+    return register;
+}
+/**
+ * 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 function parseModeSFrame(bytes) {
+    return {
+        bytes,
+        downlinkFormat: extractDownlinkFormat(bytes),
+        crcRemainder: computeCrc24(bytes),
+    };
+}

package/dist/identification.d.ts

@@ -0,0 +1,10 @@
+import type { AircraftIdentification } from './types/index.js';
+/**
+ * Decodes an ADS-B aircraft identification message (BDS 0,8, type codes
+ * 1-4).
+ *
+ * @param me - The 7-byte ME field of a DF17/18 message whose type code is 1-4.
+ * @returns The decoded callsign and category.
+ */
+export declare function decodeIdentification(me: Uint8Array): AircraftIdentification;
+//# sourceMappingURL=identification.d.ts.map

package/dist/identification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identification.d.ts","sourceRoot":"","sources":["../src/identification.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAoD/D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,GAAG,sBAAsB,CAQ3E"}

package/dist/identification.js

@@ -0,0 +1,64 @@
+import { AircraftCategory } from '@squawk/types';
+import { extractBits } from './bits.js';
+/**
+ * The 64-entry ICAO Mode-S callsign alphabet, a truncation of ASCII: 1-26
+ * map to 'A'-'Z', 32 is space, 48-57 are '0'-'9', everything else is
+ * invalid. Built once from the ASCII rule rather than hand-typed, so there
+ * is no separate string literal that could drift from the rule itself.
+ */
+const CALLSIGN_ALPHABET = buildCallsignAlphabet();
+function buildCallsignAlphabet() {
+    let table = '';
+    for (let i = 0; i < 64; i++) {
+        if (i >= 1 && i <= 26) {
+            table += String.fromCharCode(i | 0x40);
+        }
+        else if (i === 32 || (i >= 48 && i <= 57)) {
+            table += String.fromCharCode(i);
+        }
+        else {
+            table += '#';
+        }
+    }
+    return table;
+}
+function decodeCallsign(me) {
+    let callsign = '';
+    for (let i = 0; i < 8; i++) {
+        const charIndex = extractBits(me, 8 + i * 6, 6);
+        callsign += CALLSIGN_ALPHABET[charIndex] ?? '#';
+    }
+    const trimmed = callsign.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function isAircraftCategoryCode(value) {
+    return Object.hasOwn(AircraftCategory, value);
+}
+/**
+ * Maps a type code's category "set" letter (per DO-260B Table A-2-8) and
+ * the 3-bit category subfield to squawk's `AircraftCategory` key, e.g.
+ * type code 4 category 5 -> `"A5"` (heavy). Type code 1 and category 0
+ * both mean "no category information" and have no key.
+ */
+function categoryKeyFor(typeCode, category) {
+    if (category === 0) {
+        return undefined;
+    }
+    const setLetter = typeCode === 4 ? 'A' : typeCode === 3 ? 'B' : typeCode === 2 ? 'C' : undefined;
+    return setLetter === undefined ? undefined : `${setLetter}${category}`;
+}
+/**
+ * Decodes an ADS-B aircraft identification message (BDS 0,8, type codes
+ * 1-4).
+ *
+ * @param me - The 7-byte ME field of a DF17/18 message whose type code is 1-4.
+ * @returns The decoded callsign and category.
+ */
+export function decodeIdentification(me) {
+    const typeCode = extractBits(me, 0, 5);
+    const categoryBits = extractBits(me, 5, 3);
+    const callsign = decodeCallsign(me);
+    const key = categoryKeyFor(typeCode, categoryBits);
+    const category = key !== undefined && isAircraftCategoryCode(key) ? AircraftCategory[key] : undefined;
+    return { callsign, category };
+}

package/dist/identity.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Decodes a 13-bit Mode-S identity (ID) field to a 4-digit octal squawk
+ * string, per ICAO Annex 10 Vol. IV / RTCA DO-260. The field packs each
+ * octal digit across three interleaved pulse bits (e.g. digit A from bits
+ * A4, A2, A1) rather than storing the four digits contiguously.
+ *
+ * @param idField - The raw 13-bit ID field, 0-8191.
+ * @returns The 4-character octal squawk string, e.g. "1200".
+ */
+export declare function decodeIdentityCode(idField: number): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAS1D"}

package/dist/identity.js

@@ -0,0 +1,20 @@
+import { bitAt } from './bits.js';
+/** 13-bit field width shared by the identity (ID) and altitude (AC) fields. */
+const FIELD_WIDTH = 13;
+/**
+ * Decodes a 13-bit Mode-S identity (ID) field to a 4-digit octal squawk
+ * string, per ICAO Annex 10 Vol. IV / RTCA DO-260. The field packs each
+ * octal digit across three interleaved pulse bits (e.g. digit A from bits
+ * A4, A2, A1) rather than storing the four digits contiguously.
+ *
+ * @param idField - The raw 13-bit ID field, 0-8191.
+ * @returns The 4-character octal squawk string, e.g. "1200".
+ */
+export function decodeIdentityCode(idField) {
+    const bitOf = (pos) => bitAt(idField, pos, FIELD_WIDTH);
+    const a = (bitOf(5) << 2) | (bitOf(3) << 1) | bitOf(1); // A4 A2 A1
+    const b = (bitOf(11) << 2) | (bitOf(9) << 1) | bitOf(7); // B4 B2 B1
+    const c = (bitOf(4) << 2) | (bitOf(2) << 1) | bitOf(0); // C4 C2 C1
+    const d = (bitOf(12) << 2) | (bitOf(10) << 1) | bitOf(8); // D4 D2 D1
+    return `${a}${b}${c}${d}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @packageDocumentation
+ * Decode raw Mode-S/ADS-B messages: downlink format and CRC extraction,
+ * CPR position, airborne velocity, identification, and altitude decoding.
+ * Transport-agnostic - operates on already-framed message bytes regardless
+ * of where they came from (Beast, a logged capture, or any other source).
+ */
+export { decodeModeSMessage } from './message.js';
+export { decodeAcasResolutionAdvisory } from './acas.js';
+export { decodeAdsbGnssAltitude, decodeAdsbPositionAltitude, decodeAltitudeCode, } from './altitude.js';
+export { decodeHeadingAndSpeedReport, decodeSelectedVerticalIntention, decodeTrackAndTurnReport, inferCommBRegisters, } from './comm-b.js';
+export { cprNumLongitudeZones, decodeAirborneCprPair, decodeAirborneCprWithReference, decodeSurfaceCprPair, decodeSurfaceCprWithReference, } from './cpr.js';
+export { decodeEmergencyState } from './emergency-status.js';
+export { extractDownlinkFormat, computeCrc24, parseModeSFrame } from './frame.js';
+export { decodeIdentification } from './identification.js';
+export { decodeIdentityCode } from './identity.js';
+export { decodeModeAc } from './mode-ac.js';
+export { decodeAircraftOperationalStatus } from './operational-status.js';
+export { decodeSurfaceMovement } from './surface-movement.js';
+export { decodeTargetStateAndStatus } from './target-state-status.js';
+export { decodeAirborneVelocity } from './velocity.js';
+export type { AllCallReply, CommBAltitudeReply, CommBIdentityReply, DecodedModeSMessage, ExtendedSquitterAcasRaBroadcast, ExtendedSquitterCommon, ExtendedSquitterEmergencyStatus, ExtendedSquitterIdentification, ExtendedSquitterOperationalStatus, ExtendedSquitterPosition, ExtendedSquitterTargetStateAndStatus, ExtendedSquitterVelocity, LongAirAirSurveillanceReply, MessageSource, ShortAirAirSurveillanceReply, SurveillanceAltitudeReply, SurveillanceIdentityReply, } from './types/index.js';
+export type { AircraftOperationalStatus } from './types/index.js';
+export type { TargetStateAndStatus } from './types/index.js';
+export type { CommBRegister, HeadingAndSpeedReport, SelectedVerticalIntention, TrackAndTurnReport, } from './types/index.js';
+export type { AcasResolutionAdvisoryReport, AcasThreat, AcasThreatAltitudeRangeBearing, AcasThreatIcaoAddress, AcasThreatNone, AcasThreatType, ResolutionAdvisoryType, } from './types/index.js';
+export type { EmergencyState } from './types/index.js';
+export type { AircraftIdentification } from './types/index.js';
+export type { AirborneVelocity, AirborneVelocityCommon, AirSpeedVelocity, GroundSpeedVelocity, } from './types/index.js';
+export type { CprPosition, CprReference, ModeSMessageEnvelope } from './types/index.js';
+export type { ModeAcReply } from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,4BAA4B,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,2BAA2B,EAC3B,+BAA+B,EAC/B,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,+BAA+B,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,+BAA+B,EAC/B,sBAAsB,EACtB,+BAA+B,EAC/B,8BAA8B,EAC9B,iCAAiC,EACjC,wBAAwB,EACxB,oCAAoC,EACpC,wBAAwB,EACxB,2BAA2B,EAC3B,aAAa,EACb,4BAA4B,EAC5B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,4BAA4B,EAC5B,UAAU,EACV,8BAA8B,EAC9B,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxF,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @packageDocumentation
+ * Decode raw Mode-S/ADS-B messages: downlink format and CRC extraction,
+ * CPR position, airborne velocity, identification, and altitude decoding.
+ * Transport-agnostic - operates on already-framed message bytes regardless
+ * of where they came from (Beast, a logged capture, or any other source).
+ */
+export { decodeModeSMessage } from './message.js';
+export { decodeAcasResolutionAdvisory } from './acas.js';
+export { decodeAdsbGnssAltitude, decodeAdsbPositionAltitude, decodeAltitudeCode, } from './altitude.js';
+export { decodeHeadingAndSpeedReport, decodeSelectedVerticalIntention, decodeTrackAndTurnReport, inferCommBRegisters, } from './comm-b.js';
+export { cprNumLongitudeZones, decodeAirborneCprPair, decodeAirborneCprWithReference, decodeSurfaceCprPair, decodeSurfaceCprWithReference, } from './cpr.js';
+export { decodeEmergencyState } from './emergency-status.js';
+export { extractDownlinkFormat, computeCrc24, parseModeSFrame } from './frame.js';
+export { decodeIdentification } from './identification.js';
+export { decodeIdentityCode } from './identity.js';
+export { decodeModeAc } from './mode-ac.js';
+export { decodeAircraftOperationalStatus } from './operational-status.js';
+export { decodeSurfaceMovement } from './surface-movement.js';
+export { decodeTargetStateAndStatus } from './target-state-status.js';
+export { decodeAirborneVelocity } from './velocity.js';

package/dist/message.d.ts

@@ -0,0 +1,40 @@
+import type { DecodedModeSMessage } from './types/index.js';
+/**
+ * Decodes a raw Mode-S message into its typed, discriminated result.
+ *
+ * A downlink format value of 16 or higher always denotes a 112-bit (14
+ * byte) long message; below 16 always denotes a 56-bit (7 byte) short
+ * message - this holds for every downlink format, decoded or not. Any
+ * `bytes` whose length does not match what its own downlink format implies
+ * is rejected before further decoding, since a mismatch means the buffer is
+ * truncated or corrupted (e.g. a bit-flipped DF field misreading a short
+ * reply as a long one) rather than a genuine message of that format.
+ *
+ * DF17/18 (extended squitter) messages are only decoded when their CRC is
+ * exactly zero - a non-zero CRC on a squitter means the message was
+ * corrupted in transit, and this package would rather report "not
+ * decodable" than return plausible-looking but wrong data. DF18 messages
+ * are further gated on the control field: only CF=0/1/2/5/6 (which share
+ * DF17's type-code-coded ME layout) are decoded - see {@link MessageSource},
+ * which every decoded DF17/18 message carries so callers can tell a real,
+ * direct ICAO address from an anonymous or ground-derived one rather than
+ * losing that distinction after the gate. DF24 (Comm-D) is recognized
+ * but not decoded - see {@link DecodedModeSMessage}. DF19 (military
+ * extended squitter) and DF22 (military use) are reserved formats with no
+ * publicly documented payload and are not decoded, for the same reason as
+ * DF24.
+ *
+ * ```typescript
+ * import { decodeModeSMessage } from '@squawk/mode-s';
+ *
+ * const decoded = decodeModeSMessage(rawMessageBytes);
+ * if (decoded?.kind === 'extendedSquitterPosition') {
+ *   console.log(decoded.icaoHex, decoded.latCpr, decoded.lonCpr);
+ * }
+ * ```
+ *
+ * @param bytes - Raw message bytes (7 or 14 bytes).
+ * @returns The decoded message, or undefined if `bytes`' length does not match its downlink format, the downlink format is unrecognized, not decoded by this package, or the message fails its CRC check.
+ */
+export declare function decodeModeSMessage(bytes: Uint8Array): DecodedModeSMessage | undefined;
+//# sourceMappingURL=message.d.ts.map

package/dist/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,kBAAkB,CAAC;AAoN1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,GAAG,SAAS,CAqFrF"}

package/dist/message.js

@@ -0,0 +1,293 @@
+import { decodeAcasResolutionAdvisory } from './acas.js';
+import { decodeAdsbGnssAltitude, decodeAdsbPositionAltitude, decodeAltitudeCode, } from './altitude.js';
+import { extractBits, formatHexAddress } from './bits.js';
+import { inferCommBRegisters } from './comm-b.js';
+import { decodeEmergencyState } from './emergency-status.js';
+import { parseModeSFrame } from './frame.js';
+import { decodeIdentification } from './identification.js';
+import { decodeIdentityCode } from './identity.js';
+import { decodeAircraftOperationalStatus } from './operational-status.js';
+import { decodeSurfaceMovement } from './surface-movement.js';
+import { decodeTargetStateAndStatus } from './target-state-status.js';
+import { decodeAirborneVelocity } from './velocity.js';
+/**
+ * DF11's CRC remainder carries a 7-bit interrogator code field: a 1-bit IC
+ * selector plus a 6-bit value, either a legacy 4-bit II code (IC=1, low 2
+ * bits unused) or a denser 6-bit SI code (IC=0) used where more than 16
+ * co-located interrogators are in play - real values up to 127 are
+ * legitimate. A larger remainder than this suggests a corrupted message
+ * rather than a legitimate code.
+ */
+const MAX_PLAUSIBLE_INTERROGATOR_CODE = 127;
+const TYPE_CODE_CATEGORIES = [
+    { min: 0, max: 0, category: 'airborneBaroPosition' },
+    { min: 1, max: 4, category: 'identification' },
+    { min: 5, max: 8, category: 'surfacePosition' },
+    { min: 9, max: 18, category: 'airborneBaroPosition' },
+    { min: 19, max: 19, category: 'velocity' },
+    { min: 20, max: 22, category: 'airborneGnssPosition' },
+    { min: 28, max: 28, category: 'aircraftStatus' },
+    { min: 29, max: 29, category: 'targetStateAndStatus' },
+    { min: 31, max: 31, category: 'operationalStatus' },
+];
+function categorizeTypeCode(typeCode) {
+    return TYPE_CODE_CATEGORIES.find(({ min, max }) => typeCode >= min && typeCode <= max)?.category;
+}
+/**
+ * Maps a DF18 control-field (CF) value to the {@link MessageSource} it
+ * denotes - the single source of truth for both which CF values this
+ * package decodes (those with a defined case below) and what they mean.
+ * CF=3 (TIS-B, coarse format) uses a materially different field layout
+ * this package does not decode; CF=4 (TIS-B management) and CF=7
+ * (reserved) carry no per-aircraft state to decode - both fall through
+ * to `undefined`, same as an unrecognized value.
+ */
+function messageSourceForControlField(controlField) {
+    switch (controlField) {
+        case 0:
+            return 'icaoDirect';
+        case 1:
+            return 'anonymousDirect';
+        case 2:
+            return 'icaoTisb';
+        case 5:
+            return 'anonymousTisb';
+        case 6:
+            return 'adsr';
+        default:
+            return undefined;
+    }
+}
+function hexAddress(bytes, byteOffset) {
+    return formatHexAddress(extractBits(bytes, byteOffset * 8, 24));
+}
+/** Decodes the fields shared by DF0 and DF16 (both ACAS/TCAS air-air surveillance replies): recovered address, on-ground status, and altitude. DF16 additionally carries a Resolution Advisory report on top of this. */
+function decodeAirAirSurveillanceCore(bytes, crcRemainder) {
+    const acField = extractBits(bytes, 19, 13);
+    return {
+        candidateIcaoHex: formatHexAddress(crcRemainder),
+        surface: extractBits(bytes, 5, 1) === 1,
+        altitudeFt: decodeAltitudeCode(acField),
+    };
+}
+/**
+ * Decodes the three position-carrying categories (surface, airborne baro,
+ * airborne GNSS) - identical CPR field layout, differing only in what
+ * replaces the altitude bits for a surface message. Type code 0 (airborne,
+ * no position information) shares `airborneBaroPosition`'s altitude-field
+ * layout, but its CPR fields are defined as unavailable rather than a real
+ * encoded position, so `hasPosition` lets the caller omit them rather than
+ * exposing plausible-looking-but-meaningless bits.
+ */
+function decodePositionMessage(me, icaoHex, messageSource, hasPosition, category) {
+    const isSurface = category === 'surfacePosition';
+    const cprFormat = extractBits(me, 21, 1) === 1 ? 'odd' : 'even';
+    const latCpr = hasPosition ? extractBits(me, 22, 17) : undefined;
+    const lonCpr = hasPosition ? extractBits(me, 39, 17) : undefined;
+    let altitudeFt;
+    let groundSpeedKt;
+    let trueTrackDeg;
+    if (isSurface) {
+        // Surface messages replace the airborne altitude field (bits 8-19)
+        // with movement (bits 5-11) and track (bits 12-19) - a different
+        // field layout, not just a different interpretation of the same bits.
+        const movementField = extractBits(me, 5, 7);
+        const trackStatus = extractBits(me, 12, 1);
+        const trackRaw = extractBits(me, 13, 7);
+        groundSpeedKt = decodeSurfaceMovement(movementField);
+        trueTrackDeg = trackStatus === 1 ? (trackRaw * 360) / 128 : undefined;
+    }
+    else {
+        const altitudeField = extractBits(me, 8, 12);
+        altitudeFt =
+            category === 'airborneBaroPosition'
+                ? decodeAdsbPositionAltitude(altitudeField)
+                : decodeAdsbGnssAltitude(altitudeField);
+    }
+    return {
+        kind: 'extendedSquitterPosition',
+        icaoHex,
+        messageSource,
+        surface: isSurface,
+        cprFormat,
+        latCpr,
+        lonCpr,
+        altitudeFt,
+        groundSpeedKt,
+        trueTrackDeg,
+    };
+}
+function decodeExtendedSquitter(bytes, icaoHex, messageSource) {
+    const me = bytes.slice(4, 11);
+    const typeCode = extractBits(me, 0, 5);
+    const category = categorizeTypeCode(typeCode);
+    switch (category) {
+        case 'identification':
+            return {
+                kind: 'extendedSquitterIdentification',
+                icaoHex,
+                messageSource,
+                identification: decodeIdentification(me),
+            };
+        case 'velocity': {
+            const velocity = decodeAirborneVelocity(me);
+            return velocity === undefined
+                ? undefined
+                : { kind: 'extendedSquitterVelocity', icaoHex, messageSource, velocity };
+        }
+        case 'targetStateAndStatus':
+            return {
+                kind: 'extendedSquitterTargetStateAndStatus',
+                icaoHex,
+                messageSource,
+                targetStateAndStatus: decodeTargetStateAndStatus(me),
+            };
+        case 'operationalStatus':
+            return {
+                kind: 'extendedSquitterOperationalStatus',
+                icaoHex,
+                messageSource,
+                operationalStatus: decodeAircraftOperationalStatus(me),
+            };
+        case 'aircraftStatus': {
+            const subtype = extractBits(me, 5, 3);
+            if (subtype === 1) {
+                const emergencyState = decodeEmergencyState(extractBits(me, 8, 3));
+                const idField = extractBits(me, 11, 13);
+                return {
+                    kind: 'extendedSquitterEmergencyStatus',
+                    icaoHex,
+                    messageSource,
+                    emergencyState,
+                    squawk: decodeIdentityCode(idField),
+                };
+            }
+            if (subtype === 2) {
+                const resolutionAdvisory = decodeAcasResolutionAdvisory(me);
+                return resolutionAdvisory === undefined
+                    ? undefined
+                    : { kind: 'extendedSquitterAcasRaBroadcast', icaoHex, messageSource, resolutionAdvisory };
+            }
+            return undefined;
+        }
+        case 'surfacePosition':
+        case 'airborneBaroPosition':
+        case 'airborneGnssPosition':
+            return decodePositionMessage(me, icaoHex, messageSource, typeCode !== 0, category);
+        default:
+            return undefined;
+    }
+}
+/**
+ * Decodes a raw Mode-S message into its typed, discriminated result.
+ *
+ * A downlink format value of 16 or higher always denotes a 112-bit (14
+ * byte) long message; below 16 always denotes a 56-bit (7 byte) short
+ * message - this holds for every downlink format, decoded or not. Any
+ * `bytes` whose length does not match what its own downlink format implies
+ * is rejected before further decoding, since a mismatch means the buffer is
+ * truncated or corrupted (e.g. a bit-flipped DF field misreading a short
+ * reply as a long one) rather than a genuine message of that format.
+ *
+ * DF17/18 (extended squitter) messages are only decoded when their CRC is
+ * exactly zero - a non-zero CRC on a squitter means the message was
+ * corrupted in transit, and this package would rather report "not
+ * decodable" than return plausible-looking but wrong data. DF18 messages
+ * are further gated on the control field: only CF=0/1/2/5/6 (which share
+ * DF17's type-code-coded ME layout) are decoded - see {@link MessageSource},
+ * which every decoded DF17/18 message carries so callers can tell a real,
+ * direct ICAO address from an anonymous or ground-derived one rather than
+ * losing that distinction after the gate. DF24 (Comm-D) is recognized
+ * but not decoded - see {@link DecodedModeSMessage}. DF19 (military
+ * extended squitter) and DF22 (military use) are reserved formats with no
+ * publicly documented payload and are not decoded, for the same reason as
+ * DF24.
+ *
+ * ```typescript
+ * import { decodeModeSMessage } from '@squawk/mode-s';
+ *
+ * const decoded = decodeModeSMessage(rawMessageBytes);
+ * if (decoded?.kind === 'extendedSquitterPosition') {
+ *   console.log(decoded.icaoHex, decoded.latCpr, decoded.lonCpr);
+ * }
+ * ```
+ *
+ * @param bytes - Raw message bytes (7 or 14 bytes).
+ * @returns The decoded message, or undefined if `bytes`' length does not match its downlink format, the downlink format is unrecognized, not decoded by this package, or the message fails its CRC check.
+ */
+export function decodeModeSMessage(bytes) {
+    const envelope = parseModeSFrame(bytes);
+    const expectedLength = envelope.downlinkFormat >= 16 ? 14 : 7;
+    if (bytes.length !== expectedLength) {
+        return undefined;
+    }
+    if (envelope.downlinkFormat === 17 || envelope.downlinkFormat === 18) {
+        if (envelope.crcRemainder !== 0) {
+            return undefined;
+        }
+        // DF17 carries no control field - a DF17 transponder is always
+        // ICAO-addressed and transmitting its own state directly, by protocol
+        // definition, so this is a fixed value rather than a decoded one.
+        const messageSource = envelope.downlinkFormat === 17
+            ? 'icaoDirect'
+            : messageSourceForControlField(extractBits(bytes, 5, 3));
+        if (messageSource === undefined) {
+            return undefined;
+        }
+        return decodeExtendedSquitter(bytes, hexAddress(bytes, 1), messageSource);
+    }
+    if (envelope.downlinkFormat === 11) {
+        if (envelope.crcRemainder > MAX_PLAUSIBLE_INTERROGATOR_CODE) {
+            return undefined;
+        }
+        return { kind: 'allCallReply', icaoHex: hexAddress(bytes, 1) };
+    }
+    if (envelope.downlinkFormat === 0) {
+        return {
+            kind: 'shortAirAirSurveillanceReply',
+            ...decodeAirAirSurveillanceCore(bytes, envelope.crcRemainder),
+        };
+    }
+    if (envelope.downlinkFormat === 16) {
+        return {
+            kind: 'longAirAirSurveillanceReply',
+            ...decodeAirAirSurveillanceCore(bytes, envelope.crcRemainder),
+            resolutionAdvisory: decodeAcasResolutionAdvisory(bytes.slice(4, 11)),
+        };
+    }
+    if (envelope.downlinkFormat === 4) {
+        const acField = extractBits(bytes, 19, 13);
+        return {
+            kind: 'surveillanceAltitudeReply',
+            candidateIcaoHex: formatHexAddress(envelope.crcRemainder),
+            altitudeFt: decodeAltitudeCode(acField),
+        };
+    }
+    if (envelope.downlinkFormat === 20) {
+        const acField = extractBits(bytes, 19, 13);
+        return {
+            kind: 'commBAltitudeReply',
+            candidateIcaoHex: formatHexAddress(envelope.crcRemainder),
+            altitudeFt: decodeAltitudeCode(acField),
+            commBRegisters: inferCommBRegisters(bytes.slice(4, 11)),
+        };
+    }
+    if (envelope.downlinkFormat === 5) {
+        const idField = extractBits(bytes, 19, 13);
+        return {
+            kind: 'surveillanceIdentityReply',
+            candidateIcaoHex: formatHexAddress(envelope.crcRemainder),
+            squawk: decodeIdentityCode(idField),
+        };
+    }
+    if (envelope.downlinkFormat === 21) {
+        const idField = extractBits(bytes, 19, 13);
+        return {
+            kind: 'commBIdentityReply',
+            candidateIcaoHex: formatHexAddress(envelope.crcRemainder),
+            squawk: decodeIdentityCode(idField),
+            commBRegisters: inferCommBRegisters(bytes.slice(4, 11)),
+        };
+    }
+    return undefined;
+}

package/dist/mode-ac.d.ts

@@ -0,0 +1,17 @@
+import type { ModeAcReply } from './types/index.js';
+/**
+ * Decodes a Mode A/C reply, as carried by a Beast type-1 frame. Beast
+ * represents the reply as the raw big-endian 16-bit value dump1090-fa
+ * calls "ModeA" internally: each of the four squawk digits occupies one
+ * nibble (masking with `0x7777` isolates them), with the Ident pulse and a
+ * couple of spare bits interspersed.
+ *
+ * Mode A/C carries no ICAO address, so a decoded reply cannot be
+ * associated with a specific aircraft the way a Mode-S message can - it is
+ * decode-only in this package, not wired into any aircraft-tracking state.
+ *
+ * @param bytes - The 2-byte Mode A/C payload from a Beast type-1 frame.
+ * @returns The decoded squawk code, Ident flag, and altitude (if the reply looks like a valid Mode C report).
+ */
+export declare function decodeModeAc(bytes: Uint8Array): ModeAcReply;
+//# sourceMappingURL=mode-ac.d.ts.map

package/dist/mode-ac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-ac.d.ts","sourceRoot":"","sources":["../src/mode-ac.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAsEpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAO3D"}