@basmilius/apple-common 0.9.19 → 0.10.0

package/dist/index.mjs

@@ -61,6 +61,11 @@ function v4(options, buf, offset) {
 
 //#endregion
 //#region src/airplayFeatures.ts
+/**
+* AirPlay feature flags as a bitmask of bigint values. Each flag corresponds to a specific
+* capability advertised by an AirPlay device in its mDNS TXT record "features" field.
+* The bit positions match Apple's internal AirPlayFeatureFlags enum.
+*/
 const AirPlayFeatureFlags = {
 	SupportsAirPlayVideoV1: 1n << 0n,
 	SupportsAirPlayPhoto: 1n << 1n,
@@ -107,9 +112,21 @@ const AirPlayFeatureFlags = {
 	SupportsAudioMetadataControl: 1n << 60n,
 	SupportsRFC2198Redundancy: 1n << 61n
 };
+/** Bitmask in the "sf" (status flags) TXT field indicating password protection. */
 const PASSWORD_BIT = 128n;
+/** Bitmask in the "sf" TXT field indicating legacy pairing (PIN required). */
 const LEGACY_PAIRING_BIT = 512n;
+/** Bitmask in the "sf" TXT field indicating a PIN is required. */
 const PIN_REQUIRED_BIT = 8n;
+/**
+* Parses an AirPlay features string into a single bigint bitmask.
+* Features are advertised as either a single hex value or two comma-separated
+* 32-bit hex values (low,high) which are combined into a 64-bit bitmask.
+*
+* @param features - The features string from the mDNS TXT record.
+* @returns The combined feature flags as a bigint.
+* @throws If the features string has an unexpected format.
+*/
 function parseFeatures(features) {
 	const parts = features.split(",").map((part) => part.trim());
 	if (parts.length === 1) return BigInt(parts[0]);
@@ -119,14 +136,36 @@ function parseFeatures(features) {
 	}
 	throw new Error(`Invalid features format: ${features}`);
 }
+/**
+* Checks whether a specific feature flag is set in a features bitmask.
+*
+* @param features - The combined feature flags bitmask.
+* @param flag - The specific flag to check for.
+* @returns True if the flag is set.
+*/
 function hasFeatureFlag(features, flag) {
 	return (features & flag) !== 0n;
 }
+/**
+* Returns the names of all feature flags that are set in the given bitmask.
+* Useful for debugging and diagnostics output.
+*
+* @param features - The combined feature flags bitmask.
+* @returns An array of feature flag names that are active.
+*/
 function describeFlags(features) {
 	const result = [];
 	for (const [name, flag] of Object.entries(AirPlayFeatureFlags)) if (hasFeatureFlag(features, flag)) result.push(name);
 	return result;
 }
+/**
+* Determines the AirPlay protocol version supported by a device based on its
+* mDNS TXT record properties. AirPlay 2 is indicated by the presence of
+* SupportsUnifiedMediaControl or SupportsCoreUtilsPairingAndEncryption flags.
+*
+* @param txt - The key-value properties from the device's mDNS TXT record.
+* @returns 1 for legacy AirPlay, 2 for AirPlay 2.
+*/
 function getProtocolVersion(txt) {
 	const featuresStr = txt.features ?? txt.ft;
 	if (!featuresStr) return 1;
@@ -135,6 +174,14 @@ function getProtocolVersion(txt) {
 	if (hasFeatureFlag(features, AirPlayFeatureFlags.SupportsCoreUtilsPairingAndEncryption)) return 2;
 	return 1;
 }
+/**
+* Determines the pairing requirement for an AirPlay device based on its
+* feature flags and status flags. The hierarchy is:
+* HomeKit pairing > PIN required > Transient (system) pairing > Legacy PIN > None.
+*
+* @param txt - The key-value properties from the device's mDNS TXT record.
+* @returns The pairing requirement type.
+*/
 function getPairingRequirement(txt) {
 	const featuresStr = txt.features ?? txt.ft;
 	if (!featuresStr) return "none";
@@ -146,10 +193,24 @@ function getPairingRequirement(txt) {
 	if ((sf & LEGACY_PAIRING_BIT) !== 0n) return "pin";
 	return "none";
 }
+/**
+* Checks whether the AirPlay device requires a password to connect.
+* Determined by the "pw" TXT field or the password bit in the "sf" status flags.
+*
+* @param txt - The key-value properties from the device's mDNS TXT record.
+* @returns True if a password is required.
+*/
 function isPasswordRequired(txt) {
 	if (txt.pw === "true") return true;
 	return ((txt.sf ? BigInt(txt.sf) : 0n) & PASSWORD_BIT) !== 0n;
 }
+/**
+* Checks whether the AirPlay device supports remote control (Hangdog protocol).
+* Only devices with the SupportsHangdogRemoteControl flag can receive HID events.
+*
+* @param txt - The key-value properties from the device's mDNS TXT record.
+* @returns True if remote control is supported (typically Apple TV only).
+*/
 function isRemoteControlSupported(txt) {
 	const featuresStr = txt.features ?? txt.ft;
 	if (!featuresStr) return false;
@@ -158,7 +219,20 @@ function isRemoteControlSupported(txt) {
 
 //#endregion
 //#region src/storage.ts
+/**
+* Builds the composite key for credential storage lookup.
+*
+* @param deviceId - The device identifier.
+* @param protocol - The protocol type.
+* @returns A composite key in the format "deviceId:protocol".
+*/
 const credentialKey = (deviceId, protocol) => `${deviceId}:${protocol}`;
+/**
+* Converts credential buffers to base64 strings for JSON serialization.
+*
+* @param credentials - The credentials to serialize.
+* @returns A JSON-safe serialized form.
+*/
 const serializeCredentials = (credentials) => ({
 	accessoryIdentifier: credentials.accessoryIdentifier,
 	accessoryLongTermPublicKey: credentials.accessoryLongTermPublicKey.toString("base64"),
@@ -166,6 +240,12 @@ const serializeCredentials = (credentials) => ({
 	publicKey: credentials.publicKey.toString("base64"),
 	secretKey: credentials.secretKey.toString("base64")
 });
+/**
+* Restores credential buffers from base64-encoded strings.
+*
+* @param stored - The serialized credentials from storage.
+* @returns Fully hydrated credentials with Buffer fields.
+*/
 const deserializeCredentials = (stored) => ({
 	accessoryIdentifier: stored.accessoryIdentifier,
 	accessoryLongTermPublicKey: Buffer.from(stored.accessoryLongTermPublicKey, "base64"),
@@ -173,68 +253,150 @@ const deserializeCredentials = (stored) => ({
 	publicKey: Buffer.from(stored.publicKey, "base64"),
 	secretKey: Buffer.from(stored.secretKey, "base64")
 });
+/**
+* Creates an empty storage data structure with version 1 schema.
+*
+* @returns A fresh empty storage data object.
+*/
 const createEmptyData = () => ({
 	version: 1,
 	devices: {},
 	credentials: {}
 });
+/**
+* Abstract base class for persistent storage of device registrations and
+* pairing credentials. Subclasses implement the actual load/save mechanism.
+*
+* Credentials are stored keyed by "deviceId:protocol" to support per-protocol
+* pairing (a device can have separate AirPlay and Companion Link credentials).
+*/
 var Storage = class {
 	#data = createEmptyData();
+	/** The current storage data. */
 	get data() {
 		return this.#data;
 	}
+	/**
+	* Replaces the internal data with the given storage data.
+	* Used by subclasses during load.
+	*
+	* @param data - The loaded storage data to set.
+	*/
 	setData(data) {
 		this.#data = data;
 	}
+	/**
+	* Retrieves a stored device by its identifier.
+	*
+	* @param identifier - The device identifier.
+	* @returns The stored device, or undefined if not found.
+	*/
 	getDevice(identifier) {
 		return this.#data.devices[identifier];
 	}
+	/**
+	* Stores or updates a device registration.
+	*
+	* @param identifier - The device identifier.
+	* @param device - The device data to store.
+	*/
 	setDevice(identifier, device) {
 		this.#data.devices[identifier] = device;
 	}
+	/**
+	* Removes a device and all its associated credentials from storage.
+	*
+	* @param identifier - The device identifier to remove.
+	*/
 	removeDevice(identifier) {
 		delete this.#data.devices[identifier];
 		for (const key of Object.keys(this.#data.credentials)) if (key.startsWith(`${identifier}:`)) delete this.#data.credentials[key];
 	}
+	/**
+	* Returns all stored devices.
+	*
+	* @returns An array of all stored device records.
+	*/
 	listDevices() {
 		return Object.values(this.#data.devices);
 	}
+	/**
+	* Retrieves pairing credentials for a device and protocol combination.
+	*
+	* @param deviceId - The device identifier.
+	* @param protocol - The protocol type.
+	* @returns The deserialized credentials, or undefined if not found.
+	*/
 	getCredentials(deviceId, protocol) {
 		const stored = this.#data.credentials[credentialKey(deviceId, protocol)];
 		if (!stored) return;
 		return deserializeCredentials(stored);
 	}
+	/**
+	* Stores pairing credentials for a device and protocol combination.
+	*
+	* @param deviceId - The device identifier.
+	* @param protocol - The protocol type.
+	* @param credentials - The credentials to store.
+	*/
 	setCredentials(deviceId, protocol, credentials) {
 		this.#data.credentials[credentialKey(deviceId, protocol)] = serializeCredentials(credentials);
 	}
+	/**
+	* Removes pairing credentials for a device and protocol combination.
+	*
+	* @param deviceId - The device identifier.
+	* @param protocol - The protocol type.
+	*/
 	removeCredentials(deviceId, protocol) {
 		delete this.#data.credentials[credentialKey(deviceId, protocol)];
 	}
 };
+/**
+* JSON file-based storage implementation. Persists data to a JSON file on disk,
+* defaulting to `~/.config/apple-protocols/storage.json`.
+*/
 var JsonStorage = class extends Storage {
 	#path;
+	/**
+	* @param path - Optional custom file path. Defaults to `~/.config/apple-protocols/storage.json`.
+	*/
 	constructor(path) {
 		super();
 		this.#path = path ?? join(process.env.HOME ?? process.env.USERPROFILE ?? ".", ".config", "apple-protocols", "storage.json");
 	}
+	/** Loads storage data from the JSON file, if it exists. */
 	async load() {
 		if (!existsSync(this.#path)) return;
 		const raw = readFileSync(this.#path, "utf-8");
 		const json = JSON.parse(raw);
 		if (json.version === 1) this.setData(json);
 	}
+	/** Saves the current storage data to the JSON file, creating directories as needed. */
 	async save() {
 		mkdirSync(dirname(this.#path), { recursive: true });
 		writeFileSync(this.#path, JSON.stringify(this.data, null, 2), "utf-8");
 	}
 };
+/**
+* In-memory storage implementation. Data is not persisted between sessions.
+* Useful for testing or environments without filesystem access.
+*/
 var MemoryStorage = class extends Storage {
+	/** No-op: memory storage has nothing to load. */
 	async load() {}
+	/** No-op: memory storage has nothing to persist. */
 	async save() {}
 };
 
 //#endregion
 //#region src/cli.ts
+/**
+* Prompts the user for input via stdin and returns their response.
+*
+* @param message - The message to display before the input cursor.
+* @returns The user's input string.
+*/
 async function prompt(message) {
 	const cli = createInterface({
 		input: process.stdin,
@@ -244,100 +406,156 @@ async function prompt(message) {
 	cli.close();
 	return answer;
 }
+/**
+* Returns a promise that resolves after the specified delay.
+* Commonly used for timing gaps in HID press/release sequences.
+*
+* @param ms - The delay in milliseconds.
+*/
 async function waitFor(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 //#endregion
 //#region src/const.ts
+/** Default PIN used for transient (non-persistent) AirPlay pairing sessions. */
 const AIRPLAY_TRANSIENT_PIN = "3939";
+/** Timeout in milliseconds for HTTP requests during setup and control. */
 const HTTP_TIMEOUT = 6e3;
+/** Timeout in milliseconds for TCP socket connections during initial connect. */
 const SOCKET_TIMEOUT = 1e4;
+/** mDNS service type for AirPlay device discovery. */
 const AIRPLAY_SERVICE = "_airplay._tcp.local";
+/** mDNS service type for Companion Link (remote control protocol) device discovery. */
 const COMPANION_LINK_SERVICE = "_companion-link._tcp.local";
+/** mDNS service type for RAOP (Remote Audio Output Protocol) device discovery. */
 const RAOP_SERVICE = "_raop._tcp.local";
 
 //#endregion
 //#region src/errors.ts
+/**
+* Base error class for all Apple protocol errors.
+* All domain-specific errors in this library extend from this class,
+* enabling consumers to catch any protocol error with a single handler.
+*/
 var AppleProtocolError = class extends Error {
+	/** @param message - Human-readable description of the error. */
 	constructor(message) {
 		super(message);
 		this.name = "AppleProtocolError";
 	}
 };
+/**
+* Thrown when a TCP connection cannot be established or encounters a fatal error.
+* Parent class for more specific connection errors.
+*/
 var ConnectionError = class extends AppleProtocolError {
+	/** @param message - Human-readable description of the connection failure. */
 	constructor(message) {
 		super(message);
 		this.name = "ConnectionError";
 	}
 };
+/** Thrown when a TCP connection attempt exceeds the configured socket timeout. */
 var ConnectionTimeoutError = class extends ConnectionError {
+	/** @param message - Optional custom message; defaults to a standard timeout message. */
 	constructor(message = "Connection timed out.") {
 		super(message);
 		this.name = "ConnectionTimeoutError";
 	}
 };
+/** Thrown when a TCP connection is closed unexpectedly by the remote end or the OS. */
 var ConnectionClosedError = class extends ConnectionError {
+	/** @param message - Optional custom message; defaults to a standard closed message. */
 	constructor(message = "Connection closed unexpectedly.") {
 		super(message);
 		this.name = "ConnectionClosedError";
 	}
 };
+/**
+* Thrown when a pairing operation fails during the HAP pair-setup or pair-verify flow.
+* Parent class for authentication and credentials errors.
+*/
 var PairingError = class extends AppleProtocolError {
+	/** @param message - Human-readable description of the pairing failure. */
 	constructor(message) {
 		super(message);
 		this.name = "PairingError";
 	}
 };
+/**
+* Thrown when the accessory's identity verification fails, such as an invalid
+* Ed25519 signature or mismatched accessory identifier during pair-verify.
+*/
 var AuthenticationError = class extends PairingError {
+	/** @param message - Human-readable description of the authentication failure. */
 	constructor(message) {
 		super(message);
 		this.name = "AuthenticationError";
 	}
 };
+/**
+* Thrown when stored credentials are invalid, missing, or incompatible
+* with the accessory (e.g. after a factory reset).
+*/
 var CredentialsError = class extends PairingError {
+	/** @param message - Human-readable description of the credentials issue. */
 	constructor(message) {
 		super(message);
 		this.name = "CredentialsError";
 	}
 };
+/** Thrown when a protocol command fails to execute on the target device. */
 var CommandError = class extends AppleProtocolError {
+	/** @param message - Human-readable description of the command failure. */
 	constructor(message) {
 		super(message);
 		this.name = "CommandError";
 	}
 };
+/** Thrown when a protocol setup step fails (e.g. RTSP SETUP, AirPlay stream setup). */
 var SetupError = class extends AppleProtocolError {
+	/** @param message - Human-readable description of the setup failure. */
 	constructor(message) {
 		super(message);
 		this.name = "SetupError";
 	}
 };
+/** Thrown when mDNS device discovery fails or a device cannot be found after retries. */
 var DiscoveryError = class extends AppleProtocolError {
+	/** @param message - Human-readable description of the discovery failure. */
 	constructor(message) {
 		super(message);
 		this.name = "DiscoveryError";
 	}
 };
+/** Thrown when an encryption or decryption operation fails (e.g. ChaCha20 auth tag mismatch). */
 var EncryptionError = class extends AppleProtocolError {
+	/** @param message - Human-readable description of the encryption failure. */
 	constructor(message) {
 		super(message);
 		this.name = "EncryptionError";
 	}
 };
+/** Thrown when a response from the accessory is malformed or has an unexpected format. */
 var InvalidResponseError = class extends AppleProtocolError {
+	/** @param message - Human-readable description of the invalid response. */
 	constructor(message) {
 		super(message);
 		this.name = "InvalidResponseError";
 	}
 };
+/** Thrown when a protocol operation exceeds its expected time limit. */
 var TimeoutError = class extends AppleProtocolError {
+	/** @param message - Human-readable description of the timeout. */
 	constructor(message) {
 		super(message);
 		this.name = "TimeoutError";
 	}
 };
+/** Thrown when a media playback operation fails on the target device. */
 var PlaybackError = class extends AppleProtocolError {
+	/** @param message - Human-readable description of the playback failure. */
 	constructor(message) {
 		super(message);
 		this.name = "PlaybackError";
@@ -346,10 +564,15 @@ var PlaybackError = class extends AppleProtocolError {
 
 //#endregion
 //#region src/mdns.ts
+/** IPv4 multicast address for mDNS (RFC 6762). */
 const MDNS_ADDRESS = "224.0.0.251";
+/** Standard mDNS port. */
 const MDNS_PORT = 5353;
+/** Query ID used in outgoing mDNS queries. */
 const QUERY_ID = 13823;
+/** Maximum number of service queries to pack into a single DNS message. */
 const SERVICES_PER_MSG = 3;
+/** DNS record type codes used in mDNS queries and responses. */
 const QueryType = {
 	A: 1,
 	PTR: 12,
@@ -358,6 +581,12 @@ const QueryType = {
 	SRV: 33,
 	ANY: 255
 };
+/**
+* Encodes a domain name into DNS wire format (length-prefixed labels terminated by 0x00).
+*
+* @param name - The domain name to encode (e.g. "_airplay._tcp.local").
+* @returns A buffer containing the encoded QNAME.
+*/
 const encodeQName = (name) => {
 	const parts = [];
 	const labels = splitServiceName(name);
@@ -369,11 +598,25 @@ const encodeQName = (name) => {
 	parts.push(Buffer.from([0]));
 	return Buffer.concat(parts);
 };
+/**
+* Splits a service name into DNS labels, handling instance names that may contain dots.
+* For example, "Living Room._airplay._tcp.local" splits into
+* ["Living Room", "_airplay", "_tcp", "local"].
+*
+* @param name - The full service name.
+* @returns An array of DNS labels.
+*/
 const splitServiceName = (name) => {
 	const match = name.match(/\._[a-z]+\._(?:tcp|udp)\.local$/);
 	if (match) return [name.substring(0, match.index), ...match[0].substring(1).split(".")];
 	return name.split(".");
 };
+/**
+* Encodes a DNS header into a 12-byte buffer.
+*
+* @param header - The header fields to encode.
+* @returns A 12-byte buffer containing the encoded DNS header.
+*/
 const encodeDnsHeader = (header) => {
 	const buf = Buffer.allocUnsafe(12);
 	buf.writeUInt16BE(header.id, 0);
@@ -384,6 +627,14 @@ const encodeDnsHeader = (header) => {
 	buf.writeUInt16BE(header.arcount, 10);
 	return buf;
 };
+/**
+* Encodes a single DNS question section entry.
+*
+* @param name - The domain name to query.
+* @param qtype - The query type (e.g. PTR, SRV).
+* @param unicastResponse - Whether to request a unicast response (QU bit).
+* @returns A buffer containing the encoded question.
+*/
 const encodeDnsQuestion = (name, qtype, unicastResponse = false) => {
 	const qname = encodeQName(name);
 	const suffix = Buffer.allocUnsafe(4);
@@ -391,6 +642,15 @@ const encodeDnsQuestion = (name, qtype, unicastResponse = false) => {
 	suffix.writeUInt16BE(unicastResponse ? 32769 : 1, 2);
 	return Buffer.concat([qname, suffix]);
 };
+/**
+* Creates one or more DNS query packets for the given service types.
+* Services are batched into groups of {@link SERVICES_PER_MSG} per packet.
+*
+* @param services - The mDNS service types to query (e.g. '_airplay._tcp.local').
+* @param qtype - The DNS query type. Defaults to PTR.
+* @param unicastResponse - Whether to set the QU (unicast response) bit.
+* @returns An array of encoded DNS query packets.
+*/
 function createQueryPackets(services, qtype = QueryType.PTR, unicastResponse = false) {
 	const packets = [];
 	for (let i = 0; i < services.length; i += SERVICES_PER_MSG) {
@@ -408,7 +668,15 @@ function createQueryPackets(services, qtype = QueryType.PTR, unicastResponse = f
 	}
 	return packets;
 }
+/** Maximum number of pointer jumps allowed during name decompression to prevent infinite loops. */
 const MAX_POINTER_JUMPS = 128;
+/**
+* Decodes a DNS QNAME from a buffer, handling name compression pointers (RFC 1035 section 4.1.4).
+*
+* @param buf - The DNS packet buffer.
+* @param offset - The byte offset where the QNAME starts.
+* @returns A tuple of [decoded name string, next offset after the QNAME].
+*/
 const decodeQName = (buf, offset) => {
 	const labels = [];
 	let currentOffset = offset;
@@ -430,12 +698,19 @@ const decodeQName = (buf, offset) => {
 			continue;
 		}
 		currentOffset++;
+		if (currentOffset + length > buf.byteLength) break;
 		labels.push(buf.toString("utf-8", currentOffset, currentOffset + length));
 		currentOffset += length;
 		if (!jumped) returnOffset = currentOffset;
 	}
 	return [labels.join("."), returnOffset];
 };
+/**
+* Decodes a 12-byte DNS header from a buffer.
+*
+* @param buf - The DNS packet buffer (must be at least 12 bytes).
+* @returns The parsed DNS header.
+*/
 const decodeDnsHeader = (buf) => ({
 	id: buf.readUInt16BE(0),
 	flags: buf.readUInt16BE(2),
@@ -444,6 +719,13 @@ const decodeDnsHeader = (buf) => ({
 	nscount: buf.readUInt16BE(8),
 	arcount: buf.readUInt16BE(10)
 });
+/**
+* Decodes a DNS question section entry.
+*
+* @param buf - The DNS packet buffer.
+* @param offset - The byte offset where the question starts.
+* @returns A tuple of [parsed question, next offset].
+*/
 const decodeQuestion = (buf, offset) => {
 	const [qname, newOffset] = decodeQName(buf, offset);
 	return [{
@@ -452,6 +734,15 @@ const decodeQuestion = (buf, offset) => {
 		qclass: buf.readUInt16BE(newOffset + 2)
 	}, newOffset + 4];
 };
+/**
+* Decodes a DNS TXT record into key-value pairs. Each entry is a length-prefixed
+* UTF-8 string in "key=value" format.
+*
+* @param buf - The DNS packet buffer.
+* @param offset - The byte offset where the TXT rdata starts.
+* @param length - The total length of the TXT rdata.
+* @returns A record of key-value pairs.
+*/
 const decodeTxtRecord = (buf, offset, length) => {
 	const properties = {};
 	let pos = offset;
@@ -468,6 +759,13 @@ const decodeTxtRecord = (buf, offset, length) => {
 	}
 	return properties;
 };
+/**
+* Decodes a DNS SRV record containing service priority, weight, port, and target hostname.
+*
+* @param buf - The DNS packet buffer.
+* @param offset - The byte offset where the SRV rdata starts.
+* @returns The parsed SRV record.
+*/
 const decodeSrvRecord = (buf, offset) => {
 	const priority = buf.readUInt16BE(offset);
 	const weight = buf.readUInt16BE(offset + 2);
@@ -480,6 +778,14 @@ const decodeSrvRecord = (buf, offset) => {
 		target
 	};
 };
+/**
+* Decodes a DNS resource record (answer, authority, or additional section).
+* Dispatches to type-specific decoders for A, AAAA, PTR, SRV, and TXT records.
+*
+* @param buf - The DNS packet buffer.
+* @param offset - The byte offset where the resource record starts.
+* @returns A tuple of [parsed resource record, next offset].
+*/
 const decodeResource = (buf, offset) => {
 	const [qname, nameEnd] = decodeQName(buf, offset);
 	const qtype = buf.readUInt16BE(nameEnd);
@@ -519,6 +825,13 @@ const decodeResource = (buf, offset) => {
 		rdata
 	}, rdOffset + rdLength];
 };
+/**
+* Decodes a complete DNS response packet into its header, answer records,
+* and additional resource records. Skips question and authority sections.
+*
+* @param buf - The raw DNS response packet.
+* @returns The parsed header, answer records, and additional resource records.
+*/
 const decodeDnsResponse = (buf) => {
 	const header = decodeDnsHeader(buf);
 	let offset = 12;
@@ -548,11 +861,27 @@ const decodeDnsResponse = (buf) => {
 		resources
 	};
 };
+/**
+* Aggregates DNS records from multiple mDNS responses and resolves them
+* into complete service descriptions. Correlates PTR, SRV, TXT, and A records
+* to produce fully-resolved {@link MdnsService} instances.
+*/
 var ServiceCollector = class {
+	/** Maps service types to sets of instance QNAMEs (from PTR records). */
 	#ptrMap = /* @__PURE__ */ new Map();
+	/** Maps instance QNAMEs to their SRV records (port and target host). */
 	#srvMap = /* @__PURE__ */ new Map();
+	/** Maps instance QNAMEs to their TXT record properties. */
 	#txtMap = /* @__PURE__ */ new Map();
+	/** Maps hostnames to IPv4 addresses (from A records). */
 	#addressMap = /* @__PURE__ */ new Map();
+	/**
+	* Ingests DNS answer and additional resource records, categorizing them
+	* by type into the internal maps.
+	*
+	* @param answers - Answer section records.
+	* @param resources - Additional section records.
+	*/
 	addRecords(answers, resources) {
 		for (const record of [...answers, ...resources]) switch (record.qtype) {
 			case QueryType.PTR: {
@@ -572,6 +901,10 @@ var ServiceCollector = class {
 				break;
 		}
 	}
+	/**
+	* Resolves all collected records into complete service descriptions.
+	* Only returns services where all required data (PTR, SRV with non-zero port, A record) is present.
+	*/
 	get services() {
 		const results = [];
 		for (const [serviceType, instanceNames] of this.#ptrMap) for (const instanceQName of instanceNames) {
@@ -593,12 +926,20 @@ var ServiceCollector = class {
 		return results;
 	}
 };
+/** Well-known ports used to wake sleeping Apple devices via TCP SYN. */
 const WAKE_PORTS$1 = [
 	7e3,
 	3689,
 	49152,
 	32498
 ];
+/**
+* Sends TCP connection attempts ("knocks") to well-known Apple service ports
+* to wake a sleeping device before querying it.
+*
+* @param address - The IP address of the device to wake.
+* @returns A promise that resolves when all knock attempts complete (success or failure).
+*/
 const knock = (address) => {
 	const promises = WAKE_PORTS$1.map((port) => new Promise((resolve) => {
 		const socket = createConnection({
@@ -621,6 +962,16 @@ const knock = (address) => {
 	}));
 	return Promise.all(promises).then(() => {});
 };
+/**
+* Performs unicast DNS-SD queries to specific hosts. First wakes the devices
+* via TCP knocking, then repeatedly sends DNS queries via UDP to port 5353 on
+* each host, collecting responses for the specified duration.
+*
+* @param hosts - IP addresses of the specific devices to query.
+* @param services - mDNS service types to discover.
+* @param timeout - Discovery duration in seconds. Defaults to 4.
+* @returns An array of resolved mDNS services.
+*/
 function unicast(hosts, services, timeout = 4) {
 	return new Promise((resolve) => {
 		const queries = createQueryPackets(services);
@@ -658,6 +1009,19 @@ function unicast(hosts, services, timeout = 4) {
 		});
 	});
 }
+/**
+* Performs multicast DNS-SD discovery on the local network. Creates UDP sockets
+* on all network interfaces, joins the mDNS multicast group (224.0.0.251),
+* and sends periodic queries for the specified duration.
+*
+* Creates two types of sockets:
+* - One on 0.0.0.0:5353 to receive multicast responses (may fail on some platforms)
+* - One per local network interface on a random port with multicast membership
+*
+* @param services - mDNS service types to discover.
+* @param timeout - Discovery duration in seconds. Defaults to 4.
+* @returns An array of resolved mDNS services found on the network.
+*/
 function multicast(services, timeout = 4) {
 	return new Promise((resolve) => {
 		const collector = new ServiceCollector();
@@ -734,15 +1098,195 @@ function multicast(services, timeout = 4) {
 	});
 }
 
+//#endregion
+//#region src/reporter.ts
+/**
+* Scoped logger instance tagged with a device or component identifier.
+* All log output is gated by the global {@link reporter} singleton — messages
+* are only printed when the corresponding debug group is enabled.
+*/
+var Logger = class {
+	/** The identifier this logger is scoped to. */
+	get id() {
+		return this.#id;
+	}
+	/** ANSI-colored label prefix used in log output. */
+	get label() {
+		return this.#label;
+	}
+	#id;
+	#label;
+	/**
+	* @param id - Identifier used as a prefix in log output (typically a device ID or component name).
+	*/
+	constructor(id) {
+		this.#id = id;
+		this.#label = `\u001b[36m[${id}]\u001b[39m`;
+	}
+	/**
+	* Logs a debug-level message (cyan). Only printed when the 'debug' group is enabled.
+	*
+	* @param data - Values to log.
+	*/
+	debug(...data) {
+		debug(this.#label, ...data);
+	}
+	/**
+	* Logs an error-level message (red). Only printed when the 'error' group is enabled.
+	*
+	* @param data - Values to log.
+	*/
+	error(...data) {
+		error(this.#label, ...data);
+	}
+	/**
+	* Logs an info-level message (green). Only printed when the 'info' group is enabled.
+	*
+	* @param data - Values to log.
+	*/
+	info(...data) {
+		info(this.#label, ...data);
+	}
+	/**
+	* Logs a network-level message (yellow). Only printed when the 'net' group is enabled.
+	*
+	* @param data - Values to log.
+	*/
+	net(...data) {
+		net(this.#label, ...data);
+	}
+	/**
+	* Logs a raw data message (blue). Only printed when the 'raw' group is enabled.
+	* Typically used for hex dumps and binary protocol data.
+	*
+	* @param data - Values to log.
+	*/
+	raw(...data) {
+		raw(this.#label, ...data);
+	}
+	/**
+	* Logs a warning-level message (yellow). Only printed when the 'warn' group is enabled.
+	*
+	* @param data - Values to log.
+	*/
+	warn(...data) {
+		warn(this.#label, ...data);
+	}
+};
+/**
+* Global log output controller that manages which debug groups are active.
+* All {@link Logger} instances check the singleton {@link reporter} before printing.
+*/
+var Reporter = class {
+	#enabled = [];
+	/** Enables all debug groups (except 'raw' which is very verbose). */
+	all() {
+		this.#enabled = [
+			"debug",
+			"error",
+			"info",
+			"net",
+			"warn"
+		];
+	}
+	/** Disables all debug groups, silencing all log output. */
+	none() {
+		this.#enabled = [];
+	}
+	/**
+	* Disables a specific debug group.
+	*
+	* @param group - The debug group to disable.
+	*/
+	disable(group) {
+		if (this.#enabled.includes(group)) this.#enabled.splice(this.#enabled.indexOf(group), 1);
+	}
+	/**
+	* Enables a specific debug group.
+	*
+	* @param group - The debug group to enable.
+	*/
+	enable(group) {
+		if (!this.#enabled.includes(group)) this.#enabled.push(group);
+	}
+	/**
+	* Checks whether a specific debug group is currently enabled.
+	*
+	* @param group - The debug group to check.
+	* @returns True if the group is enabled.
+	*/
+	isEnabled(group) {
+		return this.#enabled.includes(group);
+	}
+};
+/**
+* Logs a debug-level message if the 'debug' group is enabled.
+*
+* @param data - Values to log.
+*/
+function debug(...data) {
+	reporter.isEnabled("debug") && console.debug(`\u001b[36m[debug]\u001b[39m`, ...data);
+}
+/**
+* Logs an error-level message if the 'error' group is enabled.
+*
+* @param data - Values to log.
+*/
+function error(...data) {
+	reporter.isEnabled("error") && console.error(`\u001b[31m[error]\u001b[39m`, ...data);
+}
+/**
+* Logs an info-level message if the 'info' group is enabled.
+*
+* @param data - Values to log.
+*/
+function info(...data) {
+	reporter.isEnabled("info") && console.info(`\u001b[32m[info]\u001b[39m`, ...data);
+}
+/**
+* Logs a network-level message if the 'net' group is enabled.
+*
+* @param data - Values to log.
+*/
+function net(...data) {
+	reporter.isEnabled("net") && console.info(`\u001b[33m[net]\u001b[39m`, ...data);
+}
+/**
+* Logs a raw data message if the 'raw' group is enabled.
+*
+* @param data - Values to log.
+*/
+function raw(...data) {
+	reporter.isEnabled("raw") && console.log(`\u001b[34m[raw]\u001b[39m`, ...data);
+}
+/**
+* Logs a warning-level message if the 'warn' group is enabled.
+*
+* @param data - Values to log.
+*/
+function warn(...data) {
+	reporter.isEnabled("warn") && console.warn(`\u001b[33m[warn]\u001b[39m`, ...data);
+}
+/** Global reporter singleton controlling which debug groups produce output. */
+const reporter = new Reporter();
+
 //#endregion
 //#region src/discovery.ts
+/** Cache time-to-live in milliseconds. */
 const CACHE_TTL = 3e4;
+/** Ports used for wake-on-network "knocking" to wake sleeping Apple devices. */
 const WAKE_PORTS = [
 	7e3,
 	3689,
 	49152,
 	32498
 ];
+/**
+* Converts a raw mDNS service record into a {@link DiscoveryResult}.
+*
+* @param service - The mDNS service record.
+* @returns A normalized discovery result.
+*/
 const toDiscoveryResult = (service) => {
 	const txt = service.properties;
 	const featuresStr = txt.features ?? txt.ft;
@@ -765,6 +1309,12 @@ const toDiscoveryResult = (service) => {
 		packet: null
 	};
 };
+/**
+* Safely parses a features string, returning undefined on failure.
+*
+* @param features - The features string to parse.
+* @returns The parsed feature bitmask, or undefined if parsing fails.
+*/
 const tryParseFeatures = (features) => {
 	try {
 		return parseFeatures(features);
@@ -772,12 +1322,32 @@ const tryParseFeatures = (features) => {
 		return;
 	}
 };
+const logger = new Logger("discovery");
+/**
+* mDNS service discovery for Apple devices on the local network.
+*
+* Supports discovering AirPlay, Companion Link, and RAOP services via multicast DNS.
+* Results are cached for 30 seconds to avoid excessive network traffic.
+* Use the static factory methods {@link Discovery.airplay}, {@link Discovery.companionLink},
+* and {@link Discovery.raop} for convenience.
+*/
 var Discovery = class Discovery {
+	/** Shared cache of discovery results, keyed by service type. */
 	static #cache = /* @__PURE__ */ new Map();
 	#service;
+	/**
+	* @param service - The mDNS service type to discover (e.g. '_airplay._tcp.local').
+	*/
 	constructor(service) {
 		this.#service = service;
 	}
+	/**
+	* Discovers devices advertising this service type via mDNS multicast.
+	* Returns cached results if available and not expired.
+	*
+	* @param useCache - Whether to use cached results. Defaults to true.
+	* @returns An array of discovered devices.
+	*/
 	async find(useCache = true) {
 		if (useCache) {
 			const cached = Discovery.#cache.get(this.#service);
@@ -792,22 +1362,37 @@ var Discovery = class Discovery {
 		});
 		return mapped;
 	}
+	/**
+	* Repeatedly searches for a specific device by ID until found or retries are exhausted.
+	* Does not use the cache to ensure fresh results on each attempt.
+	*
+	* @param id - The device ID to search for.
+	* @param tries - Maximum number of discovery attempts. Defaults to 10.
+	* @param timeout - Delay in milliseconds between attempts. Defaults to 1000.
+	* @returns The discovered device.
+	* @throws {DiscoveryError} If the device is not found after all attempts.
+	*/
 	async findUntil(id, tries = 10, timeout = 1e3) {
 		while (tries > 0) {
 			const devices = await this.find(false);
 			const device = devices.find((device) => device.id === id);
 			if (device) return device;
-			console.log();
-			console.log(`Device not found, retrying in ${timeout}ms...`);
-			console.log(devices.map((d) => ` ● ${d.id} (${d.fqdn})`).join("\n"));
+			logger.debug(`Device '${id}' not found, retrying in ${timeout}ms...`, devices.map((d) => d.id));
 			tries--;
 			await waitFor(timeout);
 		}
 		throw new DiscoveryError(`Device '${id}' not found after several tries, aborting.`);
 	}
+	/** Clears all cached discovery results across all service types. */
 	static clearCache() {
 		Discovery.#cache.clear();
 	}
+	/**
+	* Attempts to wake a sleeping Apple device by knocking on well-known ports.
+	* Sends TCP connection attempts to ports 7000, 3689, 49152, and 32498.
+	*
+	* @param address - The IP address of the device to wake.
+	*/
 	static async wake(address) {
 		const promises = WAKE_PORTS.map((port) => new Promise((resolve) => {
 			const socket = createConnection({
@@ -830,6 +1415,13 @@ var Discovery = class Discovery {
 		}));
 		await Promise.all(promises);
 	}
+	/**
+	* Discovers all Apple devices on the network across all supported service types
+	* (AirPlay, Companion Link, RAOP) and merges them by device ID.
+	*
+	* @returns An array of combined results, each representing a single physical device
+	*          with its available service endpoints.
+	*/
 	static async discoverAll() {
 		const allServices = await multicast([
 			AIRPLAY_SERVICE,
@@ -855,12 +1447,27 @@ var Discovery = class Discovery {
 		}
 		return [...devices.values()];
 	}
+	/**
+	* Creates a Discovery instance for AirPlay services.
+	*
+	* @returns A new Discovery instance targeting `_airplay._tcp.local`.
+	*/
 	static airplay() {
 		return new Discovery(AIRPLAY_SERVICE);
 	}
+	/**
+	* Creates a Discovery instance for Companion Link services.
+	*
+	* @returns A new Discovery instance targeting `_companion-link._tcp.local`.
+	*/
 	static companionLink() {
 		return new Discovery(COMPANION_LINK_SERVICE);
 	}
+	/**
+	* Creates a Discovery instance for RAOP services.
+	*
+	* @returns A new Discovery instance targeting `_raop._tcp.local`.
+	*/
 	static raop() {
 		return new Discovery(RAOP_SERVICE);
 	}
@@ -868,23 +1475,42 @@ var Discovery = class Discovery {
 
 //#endregion
 //#region src/connection.ts
+/** No-op promise handler used as a fallback when no connect promise is active. */
 const NOOP_PROMISE_HANDLER = {
 	resolve: () => {},
 	reject: (_) => {}
 };
+/**
+* TCP socket connection wrapper with built-in retry logic and typed events.
+*
+* Manages a single TCP socket to an Apple device, providing automatic reconnection
+* on failure (configurable attempts and interval), keep-alive, and no-delay settings.
+* Subclasses can extend the event map with protocol-specific events.
+*
+* Default retry behavior: 3 attempts with 3-second intervals between retries.
+*/
 var Connection = class extends EventEmitter {
+	/** The remote IP address this connection targets. */
 	get address() {
 		return this.#address;
 	}
+	/** The shared context carrying device identity and logger. */
 	get context() {
 		return this.#context;
 	}
+	/** The remote port this connection targets. */
 	get port() {
 		return this.#port;
 	}
+	/** Whether the connection is currently established and open. */
 	get isConnected() {
 		return this.#state === "connected";
 	}
+	/** The local IP address of the socket, or '0.0.0.0' if not connected. */
+	get localAddress() {
+		return this.#socket?.localAddress ?? "0.0.0.0";
+	}
+	/** The current connection state, derived from both internal state and socket readyState. */
 	get state() {
 		if (this.#state === "closing" || this.#state === "failed") return this.#state;
 		if (!this.#socket) return "disconnected";
@@ -897,7 +1523,6 @@ var Connection = class extends EventEmitter {
 	#address;
 	#port;
 	#context;
-	#emitInternal = (event, ...args) => this.emit(event, ...args);
 	#debug = false;
 	#retryAttempt = 0;
 	#retryAttempts = 3;
@@ -907,13 +1532,30 @@ var Connection = class extends EventEmitter {
 	#socket;
 	#state;
 	#connectPromise;
+	/**
+	* @param context - Shared context with device identity and logger.
+	* @param address - The remote IP address to connect to.
+	* @param port - The remote port to connect to.
+	*/
 	constructor(context, address, port) {
 		super();
 		this.#address = address;
 		this.#port = port;
 		this.#context = context;
 		this.#state = "disconnected";
+		this.onClose = this.onClose.bind(this);
+		this.onConnect = this.onConnect.bind(this);
+		this.onData = this.onData.bind(this);
+		this.onEnd = this.onEnd.bind(this);
+		this.onError = this.onError.bind(this);
+		this.onTimeout = this.onTimeout.bind(this);
 	}
+	/**
+	* Establishes a TCP connection to the remote address. If already connected,
+	* returns immediately. Enables retry logic for the duration of this connection.
+	*
+	* @throws {ConnectionError} If already connecting or all retry attempts are exhausted.
+	*/
 	async connect() {
 		if (this.#state === "connected") return;
 		if (this.#state === "connecting") throw new ConnectionError("A connection is already being established.");
@@ -921,9 +1563,14 @@ var Connection = class extends EventEmitter {
 		this.#retryAttempt = 0;
 		return this.#attemptConnect();
 	}
+	/** Immediately destroys the underlying socket without graceful shutdown. */
 	destroy() {
 		this.#socket?.destroy();
 	}
+	/**
+	* Gracefully disconnects by ending the socket and waiting for the 'close' event.
+	* Disables retry logic so the connection does not automatically reconnect.
+	*/
 	async disconnect() {
 		if (this.#retryTimeout) {
 			clearTimeout(this.#retryTimeout);
@@ -931,6 +1578,10 @@ var Connection = class extends EventEmitter {
 		}
 		this.#retryEnabled = false;
 		if (!this.#socket || this.#state === "disconnected") return;
+		if (this.#socket.destroyed || this.#socket.readyState === "closed") {
+			this.#cleanup();
+			return;
+		}
 		return new Promise((resolve) => {
 			this.#state = "closing";
 			this.#socket.once("close", () => {
@@ -940,15 +1591,34 @@ var Connection = class extends EventEmitter {
 			this.#socket.end();
 		});
 	}
+	/**
+	* Enables or disables debug logging for incoming data (hex + ASCII dumps).
+	*
+	* @param enabled - Whether to enable debug output.
+	* @returns This connection instance for chaining.
+	*/
 	debug(enabled) {
 		this.#debug = enabled;
 		return this;
 	}
+	/**
+	* Configures the retry behavior for connection attempts.
+	*
+	* @param attempts - Maximum number of retry attempts.
+	* @param interval - Delay in milliseconds between retry attempts.
+	* @returns This connection instance for chaining.
+	*/
 	retry(attempts, interval = 3e3) {
 		this.#retryAttempts = attempts;
 		this.#retryInterval = interval;
 		return this;
 	}
+	/**
+	* Writes data to the underlying TCP socket.
+	* Emits an error event if the socket is not writable.
+	*
+	* @param data - The data to send.
+	*/
 	write(data) {
 		if (!this.#socket || this.state !== "connected" || !this.#socket.writable) {
 			this.#emitInternal("error", new ConnectionClosedError("Cannot write to a disconnected connection."));
@@ -960,6 +1630,10 @@ var Connection = class extends EventEmitter {
 			this.#emitInternal("error", err);
 		});
 	}
+	/**
+	* Creates a new socket and attempts to connect. The returned promise resolves
+	* on successful connect or rejects after all retries are exhausted.
+	*/
 	async #attemptConnect() {
 		return new Promise((resolve, reject) => {
 			this.#state = "connecting";
@@ -968,16 +1642,17 @@ var Connection = class extends EventEmitter {
 				reject
 			};
 			this.#socket?.removeAllListeners();
+			this.#socket?.destroy();
 			this.#socket = void 0;
 			this.#socket = new Socket();
 			this.#socket.setNoDelay(true);
 			this.#socket.setTimeout(SOCKET_TIMEOUT);
-			this.#socket.on("close", this.#onClose.bind(this));
-			this.#socket.on("connect", this.#onConnect.bind(this));
-			this.#socket.on("data", this.#onData.bind(this));
-			this.#socket.on("end", this.#onEnd.bind(this));
-			this.#socket.on("error", this.#onError.bind(this));
-			this.#socket.on("timeout", this.#onTimeout.bind(this));
+			this.#socket.on("close", this.onClose);
+			this.#socket.on("connect", this.onConnect);
+			this.#socket.on("data", this.onData);
+			this.#socket.on("end", this.onEnd);
+			this.#socket.on("error", this.onError);
+			this.#socket.on("timeout", this.onTimeout);
 			this.#context.logger.net(`Connecting to ${this.#address}:${this.#port}...`);
 			this.#socket.connect({
 				host: this.#address,
@@ -985,6 +1660,7 @@ var Connection = class extends EventEmitter {
 			});
 		});
 	}
+	/** Removes all socket listeners, destroys the socket, and resets connection state. */
 	#cleanup() {
 		if (this.#retryTimeout) {
 			clearTimeout(this.#retryTimeout);
@@ -998,6 +1674,12 @@ var Connection = class extends EventEmitter {
 		this.#state = "disconnected";
 		this.#connectPromise = void 0;
 	}
+	/**
+	* Schedules a retry attempt after a failed connection. If all attempts are exhausted,
+	* transitions to 'failed' state and rejects the original connect promise.
+	*
+	* @param err - The error that triggered the retry.
+	*/
 	#scheduleRetry(err) {
 		if (!this.#retryEnabled || this.#retryAttempt >= this.#retryAttempts) {
 			this.#state = "failed";
@@ -1022,10 +1704,18 @@ var Connection = class extends EventEmitter {
 				};
 				await this.#attemptConnect();
 				resolve();
-			} catch (retryErr) {}
+			} catch (retryErr) {
+				reject(retryErr instanceof Error ? retryErr : new ConnectionError(String(retryErr)));
+			}
 		}, this.#retryInterval);
 	}
-	#onClose(hadError) {
+	/**
+	* Handles the socket 'close' event. If the connection was active and closed
+	* unexpectedly with an error, triggers a retry.
+	*
+	* @param hadError - Whether the close was caused by an error.
+	*/
+	onClose(hadError) {
 		const wasConnected = this.#state === "connected";
 		if (this.#state !== "closing") {
 			this.#state = "disconnected";
@@ -1034,7 +1724,11 @@ var Connection = class extends EventEmitter {
 		this.#emitInternal("close", hadError);
 		if (wasConnected && this.#retryEnabled && hadError) this.#scheduleRetry(new ConnectionClosedError());
 	}
-	#onConnect() {
+	/**
+	* Handles successful TCP connection. Enables keep-alive (10s interval),
+	* disables the connection timeout, resets retry counter, and resolves the connect promise.
+	*/
+	onConnect() {
 		this.#state = "connected";
 		this.#retryAttempt = 0;
 		this.#socket.setKeepAlive(true, 1e4);
@@ -1043,7 +1737,13 @@ var Connection = class extends EventEmitter {
 		this.#connectPromise?.resolve();
 		this.#connectPromise = void 0;
 	}
-	#onData(data) {
+	/**
+	* Handles incoming data from the socket. When debug mode is enabled,
+	* logs a hex and ASCII dump of the first 64 bytes.
+	*
+	* @param data - The received data buffer.
+	*/
+	onData(data) {
 		if (this.#debug) {
 			const cutoff = Math.min(data.byteLength, 64);
 			this.#context.logger.debug(`Received ${data.byteLength} bytes of data.`);
@@ -1052,17 +1752,27 @@ var Connection = class extends EventEmitter {
 		}
 		this.#emitInternal("data", data);
 	}
-	#onEnd() {
+	/** Handles the socket 'end' event (remote end sent FIN). */
+	onEnd() {
 		this.#emitInternal("end");
 	}
-	#onError(err) {
+	/**
+	* Handles socket errors. If connecting, schedules a retry; otherwise marks
+	* the connection as failed. Warns if no error listener is registered.
+	*
+	* @param err - The socket error.
+	*/
+	onError(err) {
 		this.#context.logger.error(`Connection error: ${err.message}`);
 		if (this.listenerCount("error") > 0) this.#emitInternal("error", err);
-		else this.#context.logger.warn("No error handler registered. This is likely a bug.", this.constructor.name, "#onError");
+		else this.#context.logger.warn("No error handler registered. This is likely a bug.", this.constructor.name, "onError");
 		if (this.#state === "connecting") this.#scheduleRetry(err);
-		else this.#state = "failed";
 	}
-	#onTimeout() {
+	/**
+	* Handles socket timeout. If connecting, schedules a retry;
+	* otherwise destroys the socket and marks the connection as failed.
+	*/
+	onTimeout() {
 		this.#context.logger.error("Connection timed out.");
 		const err = new ConnectionTimeoutError();
 		this.#emitInternal("timeout");
@@ -1072,21 +1782,60 @@ var Connection = class extends EventEmitter {
 			this.#socket?.destroy();
 		}
 	}
+	/**
+	* Type-safe internal emit that narrows the event to ConnectionEventMap keys.
+	* Needed because the merged TEventMap makes the standard emit signature too broad.
+	*
+	* @param event - The event name to emit.
+	* @param args - The event arguments.
+	* @returns Whether any listeners were called.
+	*/
+	#emitInternal(event, ...args) {
+		return this.emit(event, ...args);
+	}
 };
+/**
+* Connection subclass that adds optional ChaCha20-Poly1305 encryption.
+* Once encryption is enabled, subclasses use the {@link EncryptionState}
+* to encrypt outgoing data and decrypt incoming data with per-message nonce counters.
+*/
 var EncryptionAwareConnection = class extends Connection {
+	/** Whether encryption has been enabled on this connection. */
 	get isEncrypted() {
 		return !!this._encryption;
 	}
+	/** The current encryption state, or undefined if encryption is not enabled. */
 	_encryption;
+	/**
+	* Enables ChaCha20-Poly1305 encryption for this connection.
+	* After calling this, all subsequent data must be encrypted/decrypted
+	* using the provided keys.
+	*
+	* @param readKey - The 32-byte key for decrypting incoming data.
+	* @param writeKey - The 32-byte key for encrypting outgoing data.
+	*/
 	enableEncryption(readKey, writeKey) {
 		this._encryption = new EncryptionState(readKey, writeKey);
 	}
 };
+/**
+* Holds the symmetric encryption keys and nonce counters for a single
+* encrypted connection. Each message increments the corresponding counter
+* to ensure unique nonces for ChaCha20-Poly1305.
+*/
 var EncryptionState = class {
+	/** The 32-byte key used to decrypt incoming data. */
 	readKey;
+	/** Monotonically increasing counter used as part of the read nonce. */
 	readCount;
+	/** The 32-byte key used to encrypt outgoing data. */
 	writeKey;
+	/** Monotonically increasing counter used as part of the write nonce. */
 	writeCount;
+	/**
+	* @param readKey - The 32-byte decryption key.
+	* @param writeKey - The 32-byte encryption key.
+	*/
 	constructor(readKey, writeKey) {
 		this.readCount = 0;
 		this.readKey = readKey;
@@ -1095,98 +1844,50 @@ var EncryptionState = class {
 	}
 };
 
-//#endregion
-//#region src/reporter.ts
-var Logger = class {
-	get id() {
-		return this.#id;
-	}
-	get label() {
-		return this.#label;
-	}
-	#id;
-	#label;
-	constructor(id) {
-		this.#id = id;
-		this.#label = `\u001b[36m[${id}]\u001b[39m`;
-	}
-	debug(...data) {
-		debug(this.#label, ...data);
-	}
-	error(...data) {
-		error(this.#label, ...data);
-	}
-	info(...data) {
-		info(this.#label, ...data);
-	}
-	net(...data) {
-		net(this.#label, ...data);
-	}
-	raw(...data) {
-		raw(this.#label, ...data);
-	}
-	warn(...data) {
-		warn(this.#label, ...data);
-	}
-};
-var Reporter = class {
-	#enabled = [];
-	all() {
-		this.#enabled = [
-			"debug",
-			"error",
-			"info",
-			"net",
-			"raw",
-			"warn"
-		];
-	}
-	none() {
-		this.#enabled = [];
-	}
-	disable(group) {
-		if (this.#enabled.includes(group)) this.#enabled.splice(this.#enabled.indexOf(group), 1);
-	}
-	enable(group) {
-		if (!this.#enabled.includes(group)) this.#enabled.push(group);
-	}
-	isEnabled(group) {
-		return this.#enabled.includes(group);
-	}
-};
-function debug(...data) {
-	reporter.isEnabled("debug") && console.debug(`\u001b[36m[debug]\u001b[39m`, ...data);
-}
-function error(...data) {
-	reporter.isEnabled("error") && console.error(`\u001b[31m[error]\u001b[39m`, ...data);
-}
-function info(...data) {
-	reporter.isEnabled("info") && console.info(`\u001b[32m[info]\u001b[39m`, ...data);
-}
-function net(...data) {
-	reporter.isEnabled("net") && console.info(`\u001b[33m[net]\u001b[39m`, ...data);
-}
-function raw(...data) {
-	reporter.isEnabled("raw") && console.log(`\u001b[34m[raw]\u001b[39m`, ...data);
-}
-function warn(...data) {
-	reporter.isEnabled("warn") && console.warn(`\u001b[33m[warn]\u001b[39m`, ...data);
-}
-const reporter = new Reporter();
-
 //#endregion
 //#region src/context.ts
+/** Default identity mimicking an iPhone running the Apple TV Remote app. */
+const DEFAULT_IDENTITY = {
+	name: "apple-protocols",
+	model: "iPhone17,3",
+	osName: "iPhone OS",
+	osVersion: "26.3",
+	osBuildVersion: "25D63",
+	sourceVersion: "935.7.1",
+	applicationBundleIdentifier: "com.apple.TVRemote",
+	applicationBundleVersion: "700"
+};
+/**
+* Shared context for a device connection, carrying the device identifier,
+* the client identity presented to the accessory, and a scoped logger.
+* Passed through the entire protocol stack for consistent identification and logging.
+*/
 var Context = class {
+	/** Unique identifier of the target device (typically its mDNS hostname). */
 	get deviceId() {
 		return this.#deviceId;
 	}
+	/** The identity this client presents to the Apple device. */
+	get identity() {
+		return this.#identity;
+	}
+	/** Scoped logger instance tagged with the device identifier. */
 	get logger() {
 		return this.#logger;
 	}
 	#deviceId;
+	#identity;
 	#logger;
-	constructor(deviceId) {
+	/**
+	* @param deviceId - Unique identifier of the target device.
+	* @param identity - Optional partial override of the default device identity.
+	*/
+	constructor(deviceId, identity) {
 		this.#deviceId = deviceId;
+		this.#identity = {
+			...DEFAULT_IDENTITY,
+			...identity
+		};
 		this.#logger = new Logger(deviceId);
 	}
 };
@@ -3215,14 +3916,30 @@ var require_srp = /* @__PURE__ */ __commonJSMin(((exports) => {
 //#endregion
 //#region src/pairing.ts
 var import_srp = require_srp();
+/**
+* Abstract base class for HAP pairing operations. Provides shared TLV8
+* decoding with automatic error checking.
+*/
 var BasePairing = class {
+	/** The shared context carrying device identity and logger. */
 	get context() {
 		return this.#context;
 	}
 	#context;
+	/**
+	* @param context - Shared context for logging and device identity.
+	*/
 	constructor(context) {
 		this.#context = context;
 	}
+	/**
+	* Decodes a TLV8 buffer and checks for error codes. If the TLV contains
+	* an error value, it throws via TLV8.bail.
+	*
+	* @param buffer - The raw TLV8-encoded response.
+	* @returns A map of TLV type numbers to their buffer values.
+	* @throws If the TLV contains an error value.
+	*/
 	tlv(buffer) {
 		const data = TLV8.decode(buffer);
 		if (data.has(TLV8.Value.Error)) TLV8.bail(data);
@@ -3242,23 +3959,43 @@ var BasePairing = class {
 * For transient pairing (HomePod), only M1-M4 are needed — no long-term credentials are stored.
 */
 var AccessoryPair = class extends BasePairing {
+	/** Human-readable name sent to the accessory during pairing. */
 	#name;
+	/** Unique pairing identifier (UUID) for this controller. */
 	#pairingId;
+	/** Protocol-specific callback for sending TLV8-encoded pair-setup requests. */
 	#requestHandler;
+	/** Ed25519 public key for long-term identity. */
 	#publicKey;
+	/** Ed25519 secret key for signing identity proofs. */
 	#secretKey;
+	/** SRP client instance used for PIN-based authentication. */
 	#srp;
+	/**
+	* @param context - Shared context for logging and device identity.
+	* @param requestHandler - Callback that sends TLV8-encoded data and returns the response.
+	*/
 	constructor(context, requestHandler) {
 		super(context);
 		this.#name = "basmilius/apple-protocols";
 		this.#pairingId = Buffer.from(v4().toUpperCase());
 		this.#requestHandler = requestHandler;
 	}
+	/** Generates a new Ed25519 key pair for long-term identity. Must be called before pin() or transient(). */
 	async start() {
 		const keyPair = Ed25519.generateKeyPair();
 		this.#publicKey = Buffer.from(keyPair.publicKey);
 		this.#secretKey = Buffer.from(keyPair.secretKey);
 	}
+	/**
+	* Performs the full PIN-based pair-setup flow (M1 through M6).
+	* Prompts for a PIN via the provided callback, then completes SRP authentication
+	* and Ed25519 credential exchange with the accessory.
+	*
+	* @param askPin - Async callback that returns the user-entered PIN.
+	* @returns Long-term credentials for future pair-verify sessions.
+	* @throws {PairingError} If any step fails.
+	*/
 	async pin(askPin) {
 		const m1 = await this.m1();
 		const m2 = await this.m2(m1, await askPin());
@@ -3269,6 +4006,15 @@ var AccessoryPair = class extends BasePairing {
 		if (!m6) throw new PairingError("Pairing failed, could not get accessory keys.");
 		return m6;
 	}
+	/**
+	* Performs the transient (non-persistent) pair-setup flow (M1 through M4 only).
+	* Uses the default transient PIN ('3939'). No long-term credentials are stored;
+	* session keys are derived directly from the SRP shared secret.
+	*
+	* Primarily used for HomePod connections where persistent pairing is not required.
+	*
+	* @returns Session keys for the current connection (not reusable across sessions).
+	*/
 	async transient() {
 		const m1 = await this.m1([[TLV8.Value.Flags, TLV8.Flags.TransientPairing]]);
 		const m2 = await this.m2(m1);
@@ -3447,13 +4193,28 @@ var AccessoryPair = class extends BasePairing {
 *       → M3 (controller proof) → M4 (session key derivation)
 */
 var AccessoryVerify = class extends BasePairing {
+	/** Ephemeral Curve25519 key pair for forward-secrecy ECDH exchange. */
 	#ephemeralKeyPair;
+	/** Protocol-specific callback for sending TLV8-encoded pair-verify requests. */
 	#requestHandler;
+	/**
+	* @param context - Shared context for logging and device identity.
+	* @param requestHandler - Callback that sends TLV8-encoded data and returns the response.
+	*/
 	constructor(context, requestHandler) {
 		super(context);
 		this.#ephemeralKeyPair = Curve25519.generateKeyPair();
 		this.#requestHandler = requestHandler;
 	}
+	/**
+	* Performs the full pair-verify flow (M1 through M4) using stored credentials
+	* from a previous pair-setup. Establishes a new session with forward secrecy
+	* via ephemeral Curve25519 key exchange.
+	*
+	* @param credentials - Long-term credentials from a previous pair-setup.
+	* @returns Session keys derived from the ECDH shared secret.
+	* @throws {AuthenticationError} If the accessory's identity cannot be verified.
+	*/
 	async start(credentials) {
 		const m1 = await this.#m1();
 		const m2 = await this.#m2(credentials.accessoryIdentifier, credentials.accessoryLongTermPublicKey, m1);
@@ -3551,10 +4312,25 @@ var AccessoryVerify = class extends BasePairing {
 
 //#endregion
 //#region src/symbols.ts
+/**
+* Unique symbol used as a key for accessing encryption state on connection instances.
+* Provides type-safe access to internal encryption fields without exposing them publicly.
+*/
 const ENCRYPTION = Symbol();
 
 //#endregion
 //#region src/recovery.ts
+/**
+* Manages automatic connection recovery with exponential backoff.
+*
+* When an unexpected disconnect occurs, this class schedules retry attempts
+* with configurable delay (exponential backoff by default: base=1s, max=30s).
+* Emits 'recovering', 'recovered', and 'failed' events for monitoring.
+*
+* Optionally supports a periodic reconnect interval for proactive
+* connection health checks (failures are silent; unexpected disconnects
+* trigger the full recovery flow).
+*/
 var ConnectionRecovery = class extends EventEmitter {
 	#options;
 	#attempt = 0;
@@ -3564,6 +4340,9 @@ var ConnectionRecovery = class extends EventEmitter {
 	#retryTimeout;
 	#reconnectInterval;
 	#disposed = false;
+	/**
+	* @param options - Recovery configuration including the reconnect callback.
+	*/
 	constructor(options) {
 		super();
 		this.#options = {
@@ -3576,17 +4355,26 @@ var ConnectionRecovery = class extends EventEmitter {
 		};
 		if (this.#options.reconnectInterval > 0) this.#startReconnectInterval();
 	}
+	/** Whether a recovery attempt is currently in progress. */
 	get isRecovering() {
 		return this.#isRecovering;
 	}
+	/** The current retry attempt number (0 when not recovering). */
 	get attempt() {
 		return this.#attempt;
 	}
+	/**
+	* Called when a disconnect is detected. Only triggers recovery for
+	* unexpected disconnects; intentional disconnects are ignored.
+	*
+	* @param unexpected - Whether the disconnect was unexpected (e.g. socket error).
+	*/
 	handleDisconnect(unexpected) {
 		if (this.#disposed || !unexpected) return;
 		this.#stopReconnectInterval();
 		this.#recover();
 	}
+	/** Resets the recovery state and restarts the periodic reconnect interval if configured. */
 	reset() {
 		this.#attempt = 0;
 		this.#errors = [];
@@ -3597,6 +4385,7 @@ var ConnectionRecovery = class extends EventEmitter {
 		}
 		if (this.#options.reconnectInterval > 0) this.#startReconnectInterval();
 	}
+	/** Permanently disposes this recovery instance, cancelling all timers and removing listeners. */
 	dispose() {
 		this.#disposed = true;
 		this.#isRecovering = false;
@@ -3608,6 +4397,10 @@ var ConnectionRecovery = class extends EventEmitter {
 		this.#stopReconnectInterval();
 		this.removeAllListeners();
 	}
+	/**
+	* Initiates a recovery attempt. If max attempts are reached, emits 'failed'
+	* with all collected errors. Otherwise, schedules a delayed reconnect.
+	*/
 	#recover() {
 		if (this.#isRecovering || this.#disposed) return;
 		if (this.#attempt >= this.#options.maxAttempts) {
@@ -3634,11 +4427,22 @@ var ConnectionRecovery = class extends EventEmitter {
 			}
 		}, delay);
 	}
+	/**
+	* Calculates the delay before the next retry attempt.
+	* Uses exponential backoff (base * 2^(attempt-1)) capped at maxDelay,
+	* or a flat baseDelay if exponential backoff is disabled.
+	*
+	* @returns The delay in milliseconds.
+	*/
 	#calculateDelay() {
 		if (!this.#options.useExponentialBackoff) return this.#options.baseDelay;
 		const delay = this.#options.baseDelay * Math.pow(2, this.#attempt - 1);
 		return Math.min(delay, this.#options.maxDelay);
 	}
+	/**
+	* Starts the periodic reconnect interval. Silently calls onReconnect at the
+	* configured interval; failures do not trigger recovery (that happens via handleDisconnect).
+	*/
 	#startReconnectInterval() {
 		this.#stopReconnectInterval();
 		this.#reconnectInterval = setInterval(async () => {
@@ -3651,6 +4455,7 @@ var ConnectionRecovery = class extends EventEmitter {
 			}
 		}, this.#options.reconnectInterval);
 	}
+	/** Stops the periodic reconnect interval timer. */
 	#stopReconnectInterval() {
 		if (this.#reconnectInterval) {
 			clearInterval(this.#reconnectInterval);
@@ -3661,7 +4466,19 @@ var ConnectionRecovery = class extends EventEmitter {
 
 //#endregion
 //#region src/timing.ts
+/**
+* NTP timing server for AirPlay audio synchronization.
+*
+* Apple devices send NTP timing requests to synchronize their clocks with the
+* controller during audio streaming. This server responds with the current
+* wall-clock time using NTP packet format, enabling the device to calculate
+* the correct playback offset for synchronized multi-room audio.
+*
+* Must use wall-clock time (Date.now), not monotonic time (process.hrtime),
+* because NTP timestamps are anchored to the Unix epoch.
+*/
 var TimingServer = class {
+	/** The UDP port the timing server is listening on, or 0 if not yet bound. */
 	get port() {
 		return this.#port;
 	}
@@ -3671,14 +4488,24 @@ var TimingServer = class {
 	constructor() {
 		this.#logger = new Logger("timing-server");
 		this.#socket = createSocket("udp4");
-		this.#socket.on("connect", this.#onConnect.bind(this));
-		this.#socket.on("error", this.#onError.bind(this));
-		this.#socket.on("message", this.#onMessage.bind(this));
-	}
+		this.onConnect = this.onConnect.bind(this);
+		this.onError = this.onError.bind(this);
+		this.onMessage = this.onMessage.bind(this);
+		this.#socket.on("connect", this.onConnect);
+		this.#socket.on("error", this.onError);
+		this.#socket.on("message", this.onMessage);
+	}
+	/** Closes the UDP socket and resets the port. */
 	close() {
 		this.#socket.close();
 		this.#port = 0;
 	}
+	/**
+	* Binds the UDP socket to a random available port and starts listening
+	* for NTP timing requests.
+	*
+	* @throws If the socket fails to bind.
+	*/
 	listen() {
 		return new Promise((resolve, reject) => {
 			const onError = (err) => {
@@ -3695,18 +4522,37 @@ var TimingServer = class {
 			this.#socket.bind(0);
 		});
 	}
-	#onConnect() {
+	/**
+	* Handles the socket 'connect' event by configuring buffer sizes.
+	*/
+	onConnect() {
 		this.#socket.setRecvBufferSize(16384);
 		this.#socket.setSendBufferSize(16384);
 	}
-	#onError(err) {
+	/**
+	* Handles socket errors by logging them.
+	*
+	* @param err - The error that occurred.
+	*/
+	onError(err) {
 		this.#logger.error("Timing server error", err);
 	}
+	/**
+	* Records the bound port after the socket starts listening.
+	*/
 	#onListening() {
 		const { port } = this.#socket.address();
 		this.#port = port;
 	}
-	#onMessage(data, info) {
+	/**
+	* Handles incoming NTP timing requests from Apple devices.
+	* Decodes the request, captures the current NTP timestamp, and sends back
+	* a response with reference, receive, and send timestamps populated.
+	*
+	* @param data - The raw UDP packet data.
+	* @param info - Remote address information of the sender.
+	*/
+	onMessage(data, info) {
 		try {
 			const request = NTP.decode(data);
 			const ntp = NTP.now();
@@ -3736,15 +4582,36 @@ var TimingServer = class {
 
 //#endregion
 //#region src/utils.ts
+/**
+* Generates a random Active-Remote identifier for DACP (Digital Audio Control Protocol).
+* Used in RTSP headers to identify the remote controller.
+*
+* @returns A random 32-bit unsigned integer as a decimal string.
+*/
 function generateActiveRemoteId() {
 	return Math.floor(Math.random() * 2 ** 32).toString(10);
 }
+/**
+* Generates a random DACP-ID for identifying this controller in DACP sessions.
+*
+* @returns A random 64-bit integer as an uppercase hexadecimal string.
+*/
 function generateDacpId() {
 	return Math.floor(Math.random() * 2 ** 64).toString(16).toUpperCase();
 }
+/**
+* Generates a random session identifier for RTSP and AirPlay sessions.
+*
+* @returns A random 32-bit unsigned integer as a decimal string.
+*/
 function generateSessionId() {
 	return Math.floor(Math.random() * 2 ** 32).toString(10);
 }
+/**
+* Finds the first non-internal IPv4 address on this machine.
+*
+* @returns The local IPv4 address, or null if none is found.
+*/
 function getLocalIP() {
 	const interfaces = networkInterfaces();
 	for (const iface of Object.values(interfaces)) {
@@ -3756,6 +4623,11 @@ function getLocalIP() {
 	}
 	return null;
 }
+/**
+* Finds the first non-internal MAC address on this machine.
+*
+* @returns The MAC address in uppercase colon-separated format, or '00:00:00:00:00:00' if none is found.
+*/
 function getMacAddress() {
 	const interfaces = networkInterfaces();
 	for (const iface of Object.values(interfaces)) {
@@ -3767,17 +4639,41 @@ function getMacAddress() {
 	}
 	return "00:00:00:00:00:00";
 }
+/**
+* Generates a cryptographically random 32-bit unsigned integer.
+*
+* @returns A random unsigned 32-bit integer.
+*/
 function randomInt32() {
 	return randomBytes(4).readUInt32BE(0);
 }
+/**
+* Generates a cryptographically random 64-bit unsigned integer.
+*
+* @returns A random unsigned 64-bit bigint.
+*/
 function randomInt64() {
 	return randomBytes(8).readBigUint64LE(0);
 }
+/**
+* Encodes a 16-bit unsigned integer into a big-endian buffer.
+*
+* @param value - The 16-bit unsigned integer to encode.
+* @returns A 2-byte buffer containing the value in big-endian byte order.
+*/
 function uint16ToBE(value) {
 	const buffer = Buffer.allocUnsafe(2);
 	buffer.writeUInt16BE(value, 0);
 	return buffer;
 }
+/**
+* Encodes a 53-bit unsigned integer into an 8-byte little-endian buffer.
+* Useful for encoding JavaScript-safe integers into 64-bit wire formats.
+*
+* @param value - The unsigned integer to encode (must be in range [0, 2^53-1]).
+* @returns An 8-byte buffer containing the value in little-endian byte order.
+* @throws If the value is out of range or not an integer.
+*/
 function uint53ToLE(value) {
 	const [upper, lower] = splitUInt53(value);
 	const buffer = Buffer.allocUnsafe(8);
@@ -3785,6 +4681,13 @@ function uint53ToLE(value) {
 	buffer.writeUInt32LE(upper, 4);
 	return buffer;
 }
+/**
+* Splits a 53-bit unsigned integer into upper and lower 32-bit halves.
+*
+* @param number - The integer to split (must be in range [0, 2^53-1]).
+* @returns A tuple of [upper32, lower32].
+* @throws If the number is out of range or not an integer.
+*/
 function splitUInt53(number) {
 	const MAX_UINT32 = 4294967295;
 	if (number <= -1 || number > 9007199254740991) throw new Error("Number out of range.");
@@ -3798,6 +4701,7 @@ function splitUInt53(number) {
 
 //#endregion
 //#region src/deviceModel.ts
+/** Known Apple device models that can be discovered and controlled via AirPlay/Companion Link. */
 let DeviceModel = /* @__PURE__ */ function(DeviceModel) {
 	DeviceModel[DeviceModel["Unknown"] = 0] = "Unknown";
 	DeviceModel[DeviceModel["AppleTVGen2"] = 1] = "AppleTVGen2";
@@ -3813,6 +4717,7 @@ let DeviceModel = /* @__PURE__ */ function(DeviceModel) {
 	DeviceModel[DeviceModel["AirPortExpressGen2"] = 21] = "AirPortExpressGen2";
 	return DeviceModel;
 }({});
+/** High-level device categories derived from the specific device model. */
 let DeviceType = /* @__PURE__ */ function(DeviceType) {
 	DeviceType[DeviceType["Unknown"] = 0] = "Unknown";
 	DeviceType[DeviceType["AppleTV"] = 1] = "AppleTV";
@@ -3820,6 +4725,7 @@ let DeviceType = /* @__PURE__ */ function(DeviceType) {
 	DeviceType[DeviceType["AirPort"] = 3] = "AirPort";
 	return DeviceType;
 }({});
+/** Maps Apple model identifiers (e.g. "AppleTV6,2") to known device models. */
 const MODEL_IDENTIFIERS = {
 	"AppleTV2,1": DeviceModel.AppleTVGen2,
 	"AppleTV3,1": DeviceModel.AppleTVGen3,
@@ -3836,6 +4742,7 @@ const MODEL_IDENTIFIERS = {
 	"AirPort4,107": DeviceModel.AirPortExpress,
 	"AirPort10,115": DeviceModel.AirPortExpressGen2
 };
+/** Maps Apple internal code names (e.g. "J305AP") to known device models. */
 const INTERNAL_NAMES = {
 	"K66AP": DeviceModel.AppleTVGen2,
 	"J33AP": DeviceModel.AppleTVGen3,
@@ -3846,6 +4753,7 @@ const INTERNAL_NAMES = {
 	"J255AP": DeviceModel.AppleTV4KGen3,
 	"B520AP": DeviceModel.HomePodMini
 };
+/** Human-readable display names for each device model. */
 const MODEL_NAMES = {
 	[DeviceModel.Unknown]: "Unknown",
 	[DeviceModel.AppleTVGen2]: "Apple TV (2nd generation)",
@@ -3860,6 +4768,7 @@ const MODEL_NAMES = {
 	[DeviceModel.AirPortExpress]: "AirPort Express",
 	[DeviceModel.AirPortExpressGen2]: "AirPort Express (2nd generation)"
 };
+/** Maps each device model to its high-level device type category. */
 const MODEL_TYPES = {
 	[DeviceModel.Unknown]: DeviceType.Unknown,
 	[DeviceModel.AppleTVGen2]: DeviceType.AppleTV,
@@ -3874,11 +4783,47 @@ const MODEL_TYPES = {
 	[DeviceModel.AirPortExpress]: DeviceType.AirPort,
 	[DeviceModel.AirPortExpressGen2]: DeviceType.AirPort
 };
+/**
+* Resolves an Apple model identifier or internal code name to a known device model.
+*
+* @param identifier - Model identifier (e.g. "AppleTV6,2") or internal name (e.g. "J305AP").
+* @returns The matching device model, or {@link DeviceModel.Unknown} if unrecognized.
+*/
 const lookupDeviceModel = (identifier) => MODEL_IDENTIFIERS[identifier] ?? INTERNAL_NAMES[identifier] ?? DeviceModel.Unknown;
+/**
+* Returns the human-readable display name for a device model.
+*
+* @param model - The device model to look up.
+* @returns A display name like "Apple TV 4K (2nd generation)", or "Unknown".
+*/
 const getDeviceModelName = (model) => MODEL_NAMES[model] ?? "Unknown";
+/**
+* Returns the high-level device type category for a device model.
+*
+* @param model - The device model to categorize.
+* @returns The device type (AppleTV, HomePod, AirPort, or Unknown).
+*/
 const getDeviceType = (model) => MODEL_TYPES[model] ?? DeviceType.Unknown;
+/**
+* Checks whether the given model is an Apple TV.
+*
+* @param model - The device model to check.
+* @returns True if the model is any Apple TV generation.
+*/
 const isAppleTV = (model) => getDeviceType(model) === DeviceType.AppleTV;
+/**
+* Checks whether the given model is a HomePod.
+*
+* @param model - The device model to check.
+* @returns True if the model is any HomePod variant.
+*/
 const isHomePod = (model) => getDeviceType(model) === DeviceType.HomePod;
+/**
+* Checks whether the given model is an AirPort Express.
+*
+* @param model - The device model to check.
+* @returns True if the model is any AirPort Express generation.
+*/
 const isAirPort = (model) => getDeviceType(model) === DeviceType.AirPort;
 
 //#endregion