@basmilius/apple-devices 0.9.18 → 0.10.0

package/dist/index.mjs

@@ -1,89 +1,138 @@
 import * as AirPlay from "@basmilius/apple-airplay";
-import { DataStreamMessage, Proto, Protocol } from "@basmilius/apple-airplay";
+import { AirPlayFeature, DataStreamMessage, Proto, Protocol } from "@basmilius/apple-airplay";
 import { EventEmitter } from "node:events";
-import { waitFor } from "@basmilius/apple-common";
-import { Protocol as Protocol$1, convertAttentionState } from "@basmilius/apple-companion-link";
+import { CommandError, CredentialsError, waitFor } from "@basmilius/apple-common";
+import { MediaControlFlag, Protocol as Protocol$1, convertAttentionState } from "@basmilius/apple-companion-link";
+import { NSKeyedArchiver, Plist } from "@basmilius/apple-encoding";
 
 //#region src/airplay/player.ts
+/** Offset in seconds between the Cocoa epoch (2001-01-01) and the Unix epoch (1970-01-01). */
 const COCOA_EPOCH_OFFSET = 978307200;
+/** Default player identifier used by the Apple TV when no specific player is active. */
 const DEFAULT_PLAYER_ID = "MediaRemote-DefaultPlayer";
+/**
+* Extrapolates the current elapsed time based on a snapshot timestamp and playback rate.
+* Compensates for the time passed since the timestamp was recorded, scaled by the playback rate.
+*
+* @param elapsed - The elapsed time at the moment of the snapshot, in seconds.
+* @param cocoaTimestamp - The Cocoa epoch timestamp when the snapshot was taken.
+* @param rate - The playback rate (e.g. 1.0 for normal speed, 0 for paused).
+* @returns The extrapolated elapsed time in seconds, clamped to a minimum of 0.
+*/
 const extrapolateElapsed = (elapsed, cocoaTimestamp, rate) => {
 	if (!rate) return elapsed;
 	const timestampUnix = cocoaTimestamp + COCOA_EPOCH_OFFSET;
 	const delta = (Date.now() / 1e3 - timestampUnix) * rate;
 	return Math.max(0, elapsed + delta);
 };
+/**
+* Represents a single media player within an app on the Apple TV.
+* Each app (Client) can have multiple players (e.g. picture-in-picture).
+* Tracks now-playing metadata, playback state, and provides elapsed time extrapolation
+* based on Cocoa timestamps and playback rate.
+*/
 var Player = class {
+	/** Unique identifier for this player (e.g. a player path). */
 	get identifier() {
 		return this.#identifier;
 	}
+	/** Human-readable display name for this player. */
 	get displayName() {
 		return this.#displayName;
 	}
+	/** Whether this is the default fallback player (MediaRemote-DefaultPlayer). */
 	get isDefaultPlayer() {
 		return this.#identifier === DEFAULT_PLAYER_ID;
 	}
+	/** Raw now-playing info from the Apple TV, or null if unavailable. */
 	get nowPlayingInfo() {
 		return this.#nowPlayingInfo;
 	}
+	/** Current playback queue, or null if unavailable. */
 	get playbackQueue() {
 		return this.#playbackQueue;
 	}
+	/**
+	* Effective playback state. Corrects for the edge case where the Apple TV
+	* reports Playing but the playback rate is 0 (effectively paused).
+	*/
 	get playbackState() {
 		if (this.#playbackState === Proto.PlaybackState_Enum.Playing && this.playbackRate === 0) return Proto.PlaybackState_Enum.Paused;
 		return this.#playbackState;
 	}
+	/** The raw playback state as reported by the Apple TV, without corrections. */
 	get rawPlaybackState() {
 		return this.#playbackState;
 	}
+	/** Timestamp of the last playback state update, used to discard stale updates. */
 	get playbackStateTimestamp() {
 		return this.#playbackStateTimestamp;
 	}
+	/** List of commands supported by this player. */
 	get supportedCommands() {
 		return this.#supportedCommands;
 	}
+	/** Current track title from NowPlayingInfo or content item metadata. */
 	get title() {
 		return this.#nowPlayingInfo?.title || this.currentItemMetadata?.title || "";
 	}
+	/** Current track artist from NowPlayingInfo or content item metadata. */
 	get artist() {
 		return this.#nowPlayingInfo?.artist || this.currentItemMetadata?.trackArtistName || "";
 	}
+	/** Current track album from NowPlayingInfo or content item metadata. */
 	get album() {
 		return this.#nowPlayingInfo?.album || this.currentItemMetadata?.albumName || "";
 	}
+	/** Genre of the current content item. */
 	get genre() {
 		return this.currentItemMetadata?.genre || "";
 	}
+	/** Series name for TV show content. */
 	get seriesName() {
 		return this.currentItemMetadata?.seriesName || "";
 	}
+	/** Season number for TV show content, or 0 if not applicable. */
 	get seasonNumber() {
 		return this.currentItemMetadata?.seasonNumber || 0;
 	}
+	/** Episode number for TV show content, or 0 if not applicable. */
 	get episodeNumber() {
 		return this.currentItemMetadata?.episodeNumber || 0;
 	}
+	/** Media type of the current content item (music, video, etc.). */
 	get mediaType() {
 		return this.currentItemMetadata?.mediaType ?? Proto.ContentItemMetadata_MediaType.UnknownMediaType;
 	}
+	/** Unique content identifier for the current item (e.g. iTunes store ID). */
 	get contentIdentifier() {
 		return this.currentItemMetadata?.contentIdentifier || "";
 	}
+	/** Duration of the current track in seconds, from NowPlayingInfo or metadata. */
 	get duration() {
 		return this.#nowPlayingInfo?.duration || this.currentItemMetadata?.duration || 0;
 	}
+	/** Current playback rate (1.0 = normal, 0 = paused, 2.0 = double speed). */
 	get playbackRate() {
 		return this.#nowPlayingInfo?.playbackRate ?? this.currentItemMetadata?.playbackRate ?? 0;
 	}
+	/** Whether the player is currently playing (based on effective playback state). */
 	get isPlaying() {
-		return this.#playbackState === Proto.PlaybackState_Enum.Playing;
+		return this.playbackState === Proto.PlaybackState_Enum.Playing;
 	}
+	/** Current shuffle mode, derived from the ChangeShuffleMode command info. */
 	get shuffleMode() {
 		return this.#supportedCommands.find((c) => c.command === Proto.Command.ChangeShuffleMode)?.shuffleMode ?? Proto.ShuffleMode_Enum.Unknown;
 	}
+	/** Current repeat mode, derived from the ChangeRepeatMode command info. */
 	get repeatMode() {
 		return this.#supportedCommands.find((c) => c.command === Proto.Command.ChangeRepeatMode)?.repeatMode ?? Proto.RepeatMode_Enum.Unknown;
 	}
+	/**
+	* Extrapolated elapsed time in seconds. Uses the most recent timestamp
+	* from either NowPlayingInfo or content item metadata, accounting for
+	* playback rate to provide a real-time estimate.
+	*/
 	get elapsedTime() {
 		const npi = this.#nowPlayingInfo;
 		const meta = this.currentItemMetadata;
@@ -97,13 +146,19 @@ var Player = class {
 		if (metaValid) return extrapolateElapsed(meta.elapsedTime, meta.elapsedTimeTimestamp, meta.playbackRate);
 		return npi?.elapsedTime || meta?.elapsedTime || 0;
 	}
+	/** The currently playing content item from the playback queue, or null. */
 	get currentItem() {
 		if (!this.#playbackQueue || this.#playbackQueue.contentItems.length === 0) return null;
 		return this.#playbackQueue.contentItems[this.#playbackQueue.location] ?? this.#playbackQueue.contentItems[0] ?? null;
 	}
+	/** Metadata of the current content item, or null if no item is playing. */
 	get currentItemMetadata() {
 		return this.currentItem?.metadata ?? null;
 	}
+	/**
+	* Unique identifier for the current artwork, used for change detection.
+	* Returns null if no artwork evidence exists.
+	*/
 	get artworkId() {
 		const metadata = this.currentItemMetadata;
 		if (!metadata) return null;
@@ -112,6 +167,14 @@ var Player = class {
 		if (metadata.contentIdentifier) return metadata.contentIdentifier;
 		return this.currentItem?.identifier ?? null;
 	}
+	/**
+	* Resolves the best available artwork URL for the current item.
+	* Checks metadata artworkURL, remote artworks, and iTunes template URLs in order.
+	*
+	* @param width - Desired artwork width in pixels (used for template URLs).
+	* @param height - Desired artwork height in pixels (-1 for automatic).
+	* @returns The artwork URL, or null if no artwork URL is available.
+	*/
 	artworkUrl(width = 600, height = -1) {
 		const metadata = this.currentItemMetadata;
 		if (metadata?.artworkURL) return metadata.artworkURL;
@@ -123,6 +186,7 @@ var Player = class {
 		} catch {}
 		return null;
 	}
+	/** Raw artwork data (image bytes) for the current item, or null if not embedded. */
 	get currentItemArtwork() {
 		const item = this.currentItem;
 		if (!item) return null;
@@ -130,9 +194,11 @@ var Player = class {
 		if (item.dataArtworks.length > 0 && item.dataArtworks[0].imageData?.byteLength > 0) return item.dataArtworks[0].imageData;
 		return null;
 	}
+	/** Convenience getter for the artwork URL at default dimensions (600px). */
 	get currentItemArtworkUrl() {
 		return this.artworkUrl();
 	}
+	/** Lyrics for the current content item, or null if unavailable. */
 	get currentItemLyrics() {
 		return this.currentItem?.lyrics ?? null;
 	}
@@ -143,38 +209,84 @@ var Player = class {
 	#playbackState;
 	#playbackStateTimestamp = 0;
 	#supportedCommands = [];
+	/**
+	* Creates a new Player instance.
+	*
+	* @param identifier - Unique player identifier.
+	* @param displayName - Human-readable display name.
+	*/
 	constructor(identifier, displayName) {
 		this.#identifier = identifier;
 		this.#displayName = displayName;
 		this.#playbackState = Proto.PlaybackState_Enum.Unknown;
 	}
+	/**
+	* Finds a command by its command type in the supported commands list.
+	*
+	* @param command - The command to look up.
+	* @returns The command info, or null if not found.
+	*/
 	findCommand(command) {
 		return this.#supportedCommands.find((c) => c.command === command) ?? null;
 	}
+	/**
+	* Checks whether a command is supported and enabled.
+	*
+	* @param command - The command to check.
+	* @returns True if the command is in the supported list and enabled.
+	*/
 	isCommandSupported(command) {
 		const info = this.findCommand(command);
 		return info != null && info.enabled !== false;
 	}
+	/**
+	* Updates the now-playing info for this player.
+	*
+	* @param nowPlayingInfo - The new now-playing info from the Apple TV.
+	*/
 	setNowPlayingInfo(nowPlayingInfo) {
 		this.#nowPlayingInfo = nowPlayingInfo;
 	}
+	/**
+	* Updates the playback queue for this player.
+	*
+	* @param playbackQueue - The new playback queue from the Apple TV.
+	*/
 	setPlaybackQueue(playbackQueue) {
 		this.#playbackQueue = playbackQueue;
 	}
+	/**
+	* Updates the playback state. Ignores updates with a timestamp older than the current one
+	* to prevent stale state from overwriting newer data.
+	*
+	* @param playbackState - The new playback state.
+	* @param playbackStateTimestamp - Timestamp of this state update.
+	*/
 	setPlaybackState(playbackState, playbackStateTimestamp) {
 		if (playbackStateTimestamp < this.#playbackStateTimestamp) return;
 		this.#playbackState = playbackState;
 		this.#playbackStateTimestamp = playbackStateTimestamp;
 	}
+	/**
+	* Replaces the list of supported commands for this player.
+	*
+	* @param supportedCommands - The new list of supported commands.
+	*/
 	setSupportedCommands(supportedCommands) {
 		this.#supportedCommands = supportedCommands;
 	}
+	/**
+	* Merges updated content item data into the existing playback queue.
+	* Updates metadata, artwork, lyrics, and info fields for the matching item.
+	*
+	* @param item - The content item with updated fields.
+	*/
 	updateContentItem(item) {
 		if (!this.#playbackQueue) return;
 		const existing = this.#playbackQueue.contentItems.find((i) => i.identifier === item.identifier);
 		if (!existing) return;
 		if (item.metadata != null && existing.metadata != null) {
-			for (const [key, value] of Object.entries(item.metadata)) if (value != null) existing.metadata[key] = value;
+			for (const [key, value] of Object.entries(item.metadata)) if (value != null && !key.startsWith("$")) existing.metadata[key] = value;
 		} else if (item.metadata != null) existing.metadata = item.metadata;
 		if (item.artworkData != null) existing.artworkData = item.artworkData;
 		if (item.lyrics != null) existing.lyrics = item.lyrics;
@@ -184,31 +296,49 @@ var Player = class {
 
 //#endregion
 //#region src/airplay/client.ts
+/**
+* Represents a now-playing app (client) on the Apple TV.
+* Each client is identified by its bundle identifier and can contain multiple players.
+* Proxies now-playing getters to the active player, merging player-specific and
+* default supported commands.
+*/
 var Client = class {
+	/** Bundle identifier of the app (e.g. "com.apple.TVMusic"). */
 	get bundleIdentifier() {
 		return this.#bundleIdentifier;
 	}
+	/** Human-readable display name of the app. */
 	get displayName() {
 		return this.#displayName;
 	}
+	/** Map of all known players for this client, keyed by player identifier. */
 	get players() {
 		return this.#players;
 	}
+	/** The currently active player, or null if none is active. Falls back to the default player. */
 	get activePlayer() {
 		return this.#players.get(this.#activePlayerId ?? "MediaRemote-DefaultPlayer") ?? null;
 	}
+	/** Now-playing info from the active player, or null. */
 	get nowPlayingInfo() {
 		return this.activePlayer?.nowPlayingInfo ?? null;
 	}
+	/** Playback queue from the active player, or null. */
 	get playbackQueue() {
 		return this.activePlayer?.playbackQueue ?? null;
 	}
+	/** Playback state from the active player, or Unknown. */
 	get playbackState() {
 		return this.activePlayer?.playbackState ?? Proto.PlaybackState_Enum.Unknown;
 	}
+	/** Timestamp of the last playback state update from the active player. */
 	get playbackStateTimestamp() {
 		return this.activePlayer?.playbackStateTimestamp ?? -1;
 	}
+	/**
+	* Merged list of supported commands from the active player and client defaults.
+	* Player commands take precedence; default commands are appended if not already present.
+	*/
 	get supportedCommands() {
 		const playerCommands = this.activePlayer?.supportedCommands ?? [];
 		if (playerCommands.length === 0) return this.#defaultSupportedCommands;
@@ -218,69 +348,97 @@ var Client = class {
 		for (const cmd of this.#defaultSupportedCommands) if (!playerCommandSet.has(cmd.command)) merged.push(cmd);
 		return merged;
 	}
+	/** Current track title from the active player. */
 	get title() {
 		return this.activePlayer?.title ?? "";
 	}
+	/** Current track artist from the active player. */
 	get artist() {
 		return this.activePlayer?.artist ?? "";
 	}
+	/** Current track album from the active player. */
 	get album() {
 		return this.activePlayer?.album ?? "";
 	}
+	/** Genre of the current content from the active player. */
 	get genre() {
 		return this.activePlayer?.genre ?? "";
 	}
+	/** Series name for TV show content from the active player. */
 	get seriesName() {
 		return this.activePlayer?.seriesName ?? "";
 	}
+	/** Season number for TV show content from the active player. */
 	get seasonNumber() {
 		return this.activePlayer?.seasonNumber ?? 0;
 	}
+	/** Episode number for TV show content from the active player. */
 	get episodeNumber() {
 		return this.activePlayer?.episodeNumber ?? 0;
 	}
+	/** Media type of the current content from the active player. */
 	get mediaType() {
 		return this.activePlayer?.mediaType ?? Proto.ContentItemMetadata_MediaType.UnknownMediaType;
 	}
+	/** Content identifier of the current item from the active player. */
 	get contentIdentifier() {
 		return this.activePlayer?.contentIdentifier ?? "";
 	}
+	/** Duration of the current track in seconds from the active player. */
 	get duration() {
 		return this.activePlayer?.duration ?? 0;
 	}
+	/** Playback rate from the active player (1.0 = normal, 0 = paused). */
 	get playbackRate() {
 		return this.activePlayer?.playbackRate ?? 0;
 	}
+	/** Whether the active player is currently playing. */
 	get isPlaying() {
 		return this.activePlayer?.isPlaying ?? false;
 	}
+	/** Current shuffle mode from the active player. */
 	get shuffleMode() {
 		return this.activePlayer?.shuffleMode ?? Proto.ShuffleMode_Enum.Unknown;
 	}
+	/** Current repeat mode from the active player. */
 	get repeatMode() {
 		return this.activePlayer?.repeatMode ?? Proto.RepeatMode_Enum.Unknown;
 	}
+	/** Extrapolated elapsed time in seconds from the active player. */
 	get elapsedTime() {
 		return this.activePlayer?.elapsedTime ?? 0;
 	}
+	/** Artwork identifier for change detection from the active player. */
 	get artworkId() {
 		return this.activePlayer?.artworkId ?? null;
 	}
+	/**
+	* Resolves the best available artwork URL from the active player.
+	*
+	* @param width - Desired artwork width in pixels.
+	* @param height - Desired artwork height in pixels (-1 for automatic).
+	* @returns The artwork URL, or null if unavailable.
+	*/
 	artworkUrl(width = 600, height = -1) {
 		return this.activePlayer?.artworkUrl(width, height) ?? null;
 	}
+	/** Current content item from the active player's playback queue. */
 	get currentItem() {
 		return this.activePlayer?.currentItem ?? null;
 	}
+	/** Metadata of the current content item from the active player. */
 	get currentItemMetadata() {
 		return this.activePlayer?.currentItemMetadata ?? null;
 	}
+	/** Raw artwork data (image bytes) from the active player. */
 	get currentItemArtwork() {
 		return this.activePlayer?.currentItemArtwork ?? null;
 	}
+	/** Artwork URL at default dimensions from the active player. */
 	get currentItemArtworkUrl() {
 		return this.activePlayer?.currentItemArtworkUrl ?? null;
 	}
+	/** Lyrics for the current content item from the active player. */
 	get currentItemLyrics() {
 		return this.activePlayer?.currentItemLyrics ?? null;
 	}
@@ -289,10 +447,23 @@ var Client = class {
 	#players = /* @__PURE__ */ new Map();
 	#activePlayerId = null;
 	#defaultSupportedCommands = [];
+	/**
+	* Creates a new Client instance.
+	*
+	* @param bundleIdentifier - Bundle identifier of the app.
+	* @param displayName - Human-readable app name.
+	*/
 	constructor(bundleIdentifier, displayName) {
 		this.#bundleIdentifier = bundleIdentifier;
 		this.#displayName = displayName;
 	}
+	/**
+	* Gets an existing player or creates a new one if it does not exist.
+	*
+	* @param identifier - Unique player identifier.
+	* @param displayName - Human-readable player name (defaults to identifier).
+	* @returns The existing or newly created Player.
+	*/
 	getOrCreatePlayer(identifier, displayName) {
 		let player = this.#players.get(identifier);
 		if (!player) {
@@ -301,25 +472,61 @@ var Client = class {
 		}
 		return player;
 	}
+	/**
+	* Sets the active player by identifier.
+	*
+	* @param identifier - Identifier of the player to activate.
+	*/
 	setActivePlayer(identifier) {
 		this.#activePlayerId = identifier;
 	}
+	/**
+	* Removes a player from this client. If the removed player was active,
+	* the active player is reset to null (falling back to the default player).
+	*
+	* @param identifier - Identifier of the player to remove.
+	*/
 	removePlayer(identifier) {
 		this.#players.delete(identifier);
 		if (this.#activePlayerId === identifier) this.#activePlayerId = null;
 	}
+	/**
+	* Sets the default supported commands for this client. These are used as
+	* fallback when the active player has no commands of its own.
+	*
+	* @param supportedCommands - The default command list.
+	*/
 	setDefaultSupportedCommands(supportedCommands) {
 		this.#defaultSupportedCommands = supportedCommands;
 	}
+	/**
+	* Finds a command by type, checking the active player first,
+	* then falling back to the default supported commands.
+	*
+	* @param command - The command to look up.
+	* @returns The command info, or null if not found.
+	*/
 	findCommand(command) {
 		const playerCmd = this.activePlayer?.findCommand(command) ?? null;
 		if (playerCmd) return playerCmd;
 		return this.#defaultSupportedCommands.find((c) => c.command === command) ?? null;
 	}
+	/**
+	* Checks whether a command is supported and enabled, checking both
+	* the active player and default commands.
+	*
+	* @param command - The command to check.
+	* @returns True if the command is supported and enabled.
+	*/
 	isCommandSupported(command) {
 		const info = this.findCommand(command);
 		return info != null && info.enabled !== false;
 	}
+	/**
+	* Updates the display name for this client.
+	*
+	* @param displayName - The new display name.
+	*/
 	updateDisplayName(displayName) {
 		this.#displayName = displayName;
 	}
@@ -327,16 +534,32 @@ var Client = class {
 
 //#endregion
 //#region src/airplay/const.ts
+/** Interval in milliseconds between periodic feedback requests to keep the AirPlay session alive. */
 const FEEDBACK_INTERVAL = 2e3;
+/** Symbol used to access the underlying AirPlay Protocol instance from an AirPlayDevice. */
 const PROTOCOL = Symbol("com.basmilius.airplay:protocol");
+/** Symbol used to subscribe AirPlayState to DataStream events. */
 const STATE_SUBSCRIBE_SYMBOL = Symbol("com.basmilius.airplay:subscribe");
+/** Symbol used to unsubscribe AirPlayState from DataStream events. */
 const STATE_UNSUBSCRIBE_SYMBOL = Symbol("com.basmilius.airplay:unsubscribe");
 
 //#endregion
 //#region src/airplay/remote.ts
-var SendCommandError = class extends Error {
+/**
+* Error thrown when a SendCommand request fails on the Apple TV side.
+* Contains the specific send error and handler return status for diagnostics.
+*/
+var SendCommandError = class extends CommandError {
+	/** The send error reported by the Apple TV. */
 	sendError;
+	/** The handler return status reported by the Apple TV. */
 	handlerReturnStatus;
+	/**
+	* Creates a new SendCommandError.
+	*
+	* @param sendError - The send error code from the Apple TV.
+	* @param handlerReturnStatus - The handler return status from the Apple TV.
+	*/
 	constructor(sendError, handlerReturnStatus) {
 		super(`SendCommand failed: sendError=${Proto.SendError_Enum[sendError]}, handlerReturnStatus=${Proto.HandlerReturnStatus_Enum[handlerReturnStatus]}`);
 		this.name = "SendCommandError";
@@ -344,189 +567,398 @@ var SendCommandError = class extends Error {
 		this.handlerReturnStatus = handlerReturnStatus;
 	}
 };
+/**
+* Remote control for an AirPlay device.
+* Provides HID-based navigation and media keys (USB usage pages: Generic Desktop 0x01
+* and Consumer 0x0c), SendCommand-based media controls, keyboard/text input,
+* and touch/gesture simulation.
+*/
 var remote_default = class {
+	/** @returns The DataStream for sending HID events and commands. */
 	get #dataStream() {
 		return this.#protocol.dataStream;
 	}
+	/** @returns The underlying AirPlay Protocol instance. */
 	get #protocol() {
 		return this.#device[PROTOCOL];
 	}
 	#device;
+	/**
+	* Creates a new Remote controller.
+	*
+	* @param device - The AirPlay device to control.
+	*/
 	constructor(device) {
 		this.#device = device;
 	}
+	/** Sends an Up navigation key press (Generic Desktop, usage 0x8C). */
 	async up() {
 		await this.pressAndRelease(1, 140);
 	}
+	/** Sends a Down navigation key press (Generic Desktop, usage 0x8D). */
 	async down() {
 		await this.pressAndRelease(1, 141);
 	}
+	/** Sends a Left navigation key press (Generic Desktop, usage 0x8B). */
 	async left() {
 		await this.pressAndRelease(1, 139);
 	}
+	/** Sends a Right navigation key press (Generic Desktop, usage 0x8A). */
 	async right() {
 		await this.pressAndRelease(1, 138);
 	}
+	/** Sends a Menu key press (Generic Desktop, usage 0x86). */
 	async menu() {
 		await this.pressAndRelease(1, 134);
 	}
+	/** Sends a Select/Enter key press (Generic Desktop, usage 0x89). */
 	async select() {
 		await this.pressAndRelease(1, 137);
 	}
+	/** Sends a Home button press (Consumer, usage 0x40). */
 	async home() {
 		await this.pressAndRelease(12, 64);
 	}
+	/** Sends a Suspend/Sleep key press to put the device to sleep (Generic Desktop, usage 0x82). */
 	async suspend() {
 		await this.pressAndRelease(1, 130);
 	}
+	/** Sends a Wake key press to wake the device (Generic Desktop, usage 0x83). */
 	async wake() {
 		await this.pressAndRelease(1, 131);
 	}
+	/** Sends a Play key press (Consumer, usage 0xB0). */
 	async play() {
 		await this.pressAndRelease(12, 176);
 	}
+	/** Sends a Pause key press (Consumer, usage 0xB1). */
 	async pause() {
 		await this.pressAndRelease(12, 177);
 	}
+	/** Toggles play/pause based on the current playback state. */
 	async playPause() {
 		if (this.#device.state.nowPlayingClient?.isPlaying) await this.pause();
 		else await this.play();
 	}
+	/** Sends a Stop key press (Consumer, usage 0xB7). */
+	async stop() {
+		await this.pressAndRelease(12, 183);
+	}
+	/** Sends a Next Track key press (Consumer, usage 0xB5). */
 	async next() {
 		await this.pressAndRelease(12, 181);
 	}
+	/** Sends a Previous Track key press (Consumer, usage 0xB6). */
 	async previous() {
 		await this.pressAndRelease(12, 182);
 	}
+	/** Sends a Volume Up key press (Consumer, usage 0xE9). */
 	async volumeUp() {
 		await this.pressAndRelease(12, 233);
 	}
+	/** Sends a Volume Down key press (Consumer, usage 0xEA). */
 	async volumeDown() {
 		await this.pressAndRelease(12, 234);
 	}
+	/** Sends a Mute key press (Consumer, usage 0xE2). */
 	async mute() {
 		await this.pressAndRelease(12, 226);
 	}
+	/** Sends a Top Menu key press (Consumer, usage 0x60). */
+	async topMenu() {
+		await this.pressAndRelease(12, 96);
+	}
+	/** Sends a Channel Up key press (Consumer, usage 0x9C). */
+	async channelUp() {
+		await this.pressAndRelease(12, 156);
+	}
+	/** Sends a Channel Down key press (Consumer, usage 0x9D). */
+	async channelDown() {
+		await this.pressAndRelease(12, 157);
+	}
+	/** Sends a Play command via the MRP SendCommand protocol. */
 	async commandPlay() {
 		await this.#sendCommand(Proto.Command.Play);
 	}
+	/** Sends a Pause command via the MRP SendCommand protocol. */
 	async commandPause() {
 		await this.#sendCommand(Proto.Command.Pause);
 	}
+	/** Sends a TogglePlayPause command via the MRP SendCommand protocol. */
 	async commandTogglePlayPause() {
 		await this.#sendCommand(Proto.Command.TogglePlayPause);
 	}
+	/** Sends a Stop command via the MRP SendCommand protocol. */
 	async commandStop() {
 		await this.#sendCommand(Proto.Command.Stop);
 	}
+	/** Sends a NextTrack command via the MRP SendCommand protocol. */
 	async commandNextTrack() {
 		await this.#sendCommand(Proto.Command.NextTrack);
 	}
+	/** Sends a PreviousTrack command via the MRP SendCommand protocol. */
 	async commandPreviousTrack() {
 		await this.#sendCommand(Proto.Command.PreviousTrack);
 	}
+	/**
+	* Sends a SkipForward command with a configurable interval.
+	*
+	* @param interval - Seconds to skip forward (defaults to 15).
+	*/
 	async commandSkipForward(interval = 15) {
 		await this.#sendCommandRaw(DataStreamMessage.sendCommandWithSkipInterval(Proto.Command.SkipForward, interval));
 	}
+	/**
+	* Sends a SkipBackward command with a configurable interval.
+	*
+	* @param interval - Seconds to skip backward (defaults to 15).
+	*/
 	async commandSkipBackward(interval = 15) {
 		await this.#sendCommandRaw(DataStreamMessage.sendCommandWithSkipInterval(Proto.Command.SkipBackward, interval));
 	}
+	/**
+	* Seeks to an absolute playback position.
+	*
+	* @param position - The target position in seconds.
+	*/
 	async commandSeekToPosition(position) {
 		await this.#sendCommandRaw(DataStreamMessage.sendCommandWithPlaybackPosition(Proto.Command.SeekToPlaybackPosition, position));
 	}
+	/**
+	* Sets the shuffle mode.
+	*
+	* @param mode - The desired shuffle mode.
+	*/
 	async commandSetShuffleMode(mode) {
 		await this.#sendCommandRaw(DataStreamMessage.sendCommandWithShuffleMode(Proto.Command.ChangeShuffleMode, mode));
 	}
+	/**
+	* Sets the repeat mode.
+	*
+	* @param mode - The desired repeat mode.
+	*/
 	async commandSetRepeatMode(mode) {
 		await this.#sendCommandRaw(DataStreamMessage.sendCommandWithRepeatMode(Proto.Command.ChangeRepeatMode, mode));
 	}
+	/**
+	* Changes the playback rate (speed).
+	*
+	* @param rate - The desired playback rate (e.g. 1.0 for normal, 2.0 for double speed).
+	*/
 	async commandChangePlaybackRate(rate) {
 		await this.#sendCommandRaw(DataStreamMessage.sendCommandWithPlaybackRate(Proto.Command.ChangePlaybackRate, rate));
 	}
+	/** Cycles the shuffle mode to the next value. */
 	async commandAdvanceShuffleMode() {
 		await this.#sendCommand(Proto.Command.AdvanceShuffleMode);
 	}
+	/** Cycles the repeat mode to the next value. */
 	async commandAdvanceRepeatMode() {
 		await this.#sendCommand(Proto.Command.AdvanceRepeatMode);
 	}
+	/** Begins fast-forwarding playback. */
 	async commandBeginFastForward() {
 		await this.#sendCommand(Proto.Command.BeginFastForward);
 	}
+	/** Ends fast-forwarding playback. */
 	async commandEndFastForward() {
 		await this.#sendCommand(Proto.Command.EndFastForward);
 	}
+	/** Begins rewinding playback. */
 	async commandBeginRewind() {
 		await this.#sendCommand(Proto.Command.BeginRewind);
 	}
+	/** Ends rewinding playback. */
 	async commandEndRewind() {
 		await this.#sendCommand(Proto.Command.EndRewind);
 	}
+	/** Skips to the next chapter. */
 	async commandNextChapter() {
 		await this.#sendCommand(Proto.Command.NextChapter);
 	}
+	/** Skips to the previous chapter. */
 	async commandPreviousChapter() {
 		await this.#sendCommand(Proto.Command.PreviousChapter);
 	}
+	/** Marks the current track as liked. */
 	async commandLikeTrack() {
 		await this.#sendCommand(Proto.Command.LikeTrack);
 	}
+	/** Marks the current track as disliked. */
 	async commandDislikeTrack() {
 		await this.#sendCommand(Proto.Command.DislikeTrack);
 	}
+	/** Bookmarks the current track. */
 	async commandBookmarkTrack() {
 		await this.#sendCommand(Proto.Command.BookmarkTrack);
 	}
+	/** Adds the currently playing item to the user's library. */
 	async commandAddNowPlayingItemToLibrary() {
 		await this.#sendCommand(Proto.Command.AddNowPlayingItemToLibrary);
 	}
+	/**
+	* Sets the text input field to the given text, replacing any existing content.
+	*
+	* @param text - The text to set.
+	*/
+	async textSet(text) {
+		await this.#dataStream.send(DataStreamMessage.textInput(text, Proto.ActionType_Enum.Set));
+	}
+	/**
+	* Appends text to the current text input field content.
+	*
+	* @param text - The text to append.
+	*/
+	async textAppend(text) {
+		await this.#dataStream.send(DataStreamMessage.textInput(text, Proto.ActionType_Enum.Insert));
+	}
+	/** Clears the text input field. */
+	async textClear() {
+		await this.#dataStream.send(DataStreamMessage.textInput("", Proto.ActionType_Enum.ClearAction));
+	}
+	/** Requests the current keyboard session state from the Apple TV. */
+	async getKeyboardSession() {
+		await this.#dataStream.send(DataStreamMessage.getKeyboardSession());
+	}
+	/**
+	* Simulates a tap at the given coordinates.
+	*
+	* @param x - Horizontal position in the virtual touch area.
+	* @param y - Vertical position in the virtual touch area.
+	* @param finger - Finger index for multi-touch (defaults to 1).
+	*/
 	async tap(x, y, finger = 1) {
 		await this.#sendTouch(x, y, 1, finger);
 		await waitFor(50);
 		await this.#sendTouch(x, y, 4, finger);
 	}
+	/**
+	* Simulates an upward swipe gesture.
+	*
+	* @param duration - Swipe duration in milliseconds (defaults to 200).
+	*/
 	async swipeUp(duration = 200) {
 		await this.#swipe(200, 400, 200, 100, duration);
 	}
+	/**
+	* Simulates a downward swipe gesture.
+	*
+	* @param duration - Swipe duration in milliseconds (defaults to 200).
+	*/
 	async swipeDown(duration = 200) {
 		await this.#swipe(200, 100, 200, 400, duration);
 	}
+	/**
+	* Simulates a leftward swipe gesture.
+	*
+	* @param duration - Swipe duration in milliseconds (defaults to 200).
+	*/
 	async swipeLeft(duration = 200) {
 		await this.#swipe(400, 200, 100, 200, duration);
 	}
+	/**
+	* Simulates a rightward swipe gesture.
+	*
+	* @param duration - Swipe duration in milliseconds (defaults to 200).
+	*/
 	async swipeRight(duration = 200) {
 		await this.#swipe(100, 200, 400, 200, duration);
 	}
+	/**
+	* Sends a double press of a HID key (two press-and-release cycles with a 150ms gap).
+	*
+	* @param usePage - USB HID usage page (1 = Generic Desktop, 12 = Consumer).
+	* @param usage - USB HID usage code.
+	*/
 	async doublePress(usePage, usage) {
 		await this.pressAndRelease(usePage, usage);
 		await waitFor(150);
 		await this.pressAndRelease(usePage, usage);
 	}
+	/**
+	* Sends a long press of a HID key (hold for a configurable duration).
+	*
+	* @param usePage - USB HID usage page (1 = Generic Desktop, 12 = Consumer).
+	* @param usage - USB HID usage code.
+	* @param duration - Hold duration in milliseconds (defaults to 1000).
+	*/
 	async longPress(usePage, usage, duration = 1e3) {
 		await this.#dataStream.exchange(DataStreamMessage.sendHIDEvent(usePage, usage, true));
 		await waitFor(duration);
 		await this.#dataStream.exchange(DataStreamMessage.sendHIDEvent(usePage, usage, false));
 	}
+	/**
+	* Sends a single press-and-release of a HID key with a 25ms hold.
+	*
+	* @param usePage - USB HID usage page (1 = Generic Desktop, 12 = Consumer).
+	* @param usage - USB HID usage code.
+	*/
 	async pressAndRelease(usePage, usage) {
 		await this.#dataStream.exchange(DataStreamMessage.sendHIDEvent(usePage, usage, true));
 		await waitFor(25);
 		await this.#dataStream.exchange(DataStreamMessage.sendHIDEvent(usePage, usage, false));
 	}
+	/**
+	* Sends a SendCommand request and checks the result.
+	*
+	* @param command - The command to send.
+	* @param options - Optional command options.
+	* @returns The command result message, or undefined if no result was returned.
+	* @throws SendCommandError when the Apple TV reports a send error.
+	*/
 	async #sendCommand(command, options) {
 		const response = await this.#dataStream.exchange(DataStreamMessage.sendCommand(command, options));
 		return this.#checkCommandResult(response);
 	}
+	/**
+	* Sends a pre-built command message and checks the result.
+	*
+	* @param message - The pre-built DataStream message to send.
+	* @returns The command result message, or undefined if no result was returned.
+	* @throws SendCommandError when the Apple TV reports a send error.
+	*/
 	async #sendCommandRaw(message) {
 		const response = await this.#dataStream.exchange(message);
 		return this.#checkCommandResult(response);
 	}
+	/**
+	* Validates the response from a SendCommand request and throws on error.
+	*
+	* @param response - The protocol message response.
+	* @returns The decoded result, or undefined if the response has no result extension.
+	* @throws SendCommandError when the result indicates a send error.
+	*/
 	#checkCommandResult(response) {
-		const result = DataStreamMessage.getExtension(response, Proto.sendCommandResultMessage);
+		let result;
+		try {
+			result = DataStreamMessage.getExtension(response, Proto.sendCommandResultMessage);
+		} catch {
+			return;
+		}
+		if (!result) return;
 		if (result.sendError !== Proto.SendError_Enum.NoError) throw new SendCommandError(result.sendError, result.handlerReturnStatus);
 		return result;
 	}
+	/**
+	* Sends a virtual touch event at the given coordinates.
+	*
+	* @param x - Horizontal position.
+	* @param y - Vertical position.
+	* @param phase - Touch phase (1 = Began, 2 = Moved, 4 = Ended).
+	* @param finger - Finger index for multi-touch.
+	*/
 	async #sendTouch(x, y, phase, finger) {
 		await this.#dataStream.exchange(DataStreamMessage.sendVirtualTouchEvent(x, y, phase, finger));
 	}
+	/**
+	* Performs a swipe gesture by interpolating touch events between start and end coordinates.
+	*
+	* @param startX - Starting horizontal position.
+	* @param startY - Starting vertical position.
+	* @param endX - Ending horizontal position.
+	* @param endY - Ending vertical position.
+	* @param duration - Total swipe duration in milliseconds.
+	*/
 	async #swipe(startX, startY, endX, endY, duration) {
 		const steps = Math.max(4, Math.floor(duration / 50));
 		const deltaX = (endX - startX) / steps;
@@ -544,47 +976,108 @@ var remote_default = class {
 
 //#endregion
 //#region src/airplay/state.ts
+/**
+* Tracks the complete state of an AirPlay device: clients, players, now-playing,
+* volume, keyboard, output devices, and cluster info.
+* Listens to DataStream protocol messages and emits both low-level (1:1 with protocol)
+* and high-level (deduplicated, resolved) events.
+*/
 var state_default = class extends EventEmitter {
+	/** @returns The DataStream for event subscription. */
 	get #dataStream() {
 		return this.#protocol.dataStream;
 	}
+	/** @returns The underlying AirPlay Protocol instance. */
 	get #protocol() {
 		return this.#device[PROTOCOL];
 	}
+	/** All known clients (apps) keyed by bundle identifier. */
 	get clients() {
 		return this.#clients;
 	}
+	/** Whether a keyboard/text input session is currently active on the Apple TV. */
+	get isKeyboardActive() {
+		return this.#keyboardState === Proto.KeyboardState_Enum.DidBeginEditing || this.#keyboardState === Proto.KeyboardState_Enum.Editing || this.#keyboardState === Proto.KeyboardState_Enum.TextDidChange;
+	}
+	/** Text editing attributes for the active keyboard session, or null. */
+	get keyboardAttributes() {
+		return this.#keyboardAttributes;
+	}
+	/** Current keyboard state enum value. */
+	get keyboardState() {
+		return this.#keyboardState;
+	}
+	/** The currently active now-playing client, or null if nothing is playing. */
 	get nowPlayingClient() {
 		return this.#nowPlayingClientBundleIdentifier ? this.#clients[this.#nowPlayingClientBundleIdentifier] ?? null : null;
 	}
+	/** UID of the primary output device (used for volume control and multi-room). */
 	get outputDeviceUID() {
 		return this.#outputDeviceUID;
 	}
+	/** List of all output device descriptors in the current AirPlay group. */
 	get outputDevices() {
 		return this.#outputDevices;
 	}
+	/** Cluster identifier for multi-room groups, or null. */
+	get clusterID() {
+		return this.#clusterID;
+	}
+	/** Cluster type code (0 if not clustered). */
+	get clusterType() {
+		return this.#clusterType;
+	}
+	/** Whether this device is aware of multi-room clusters. */
+	get isClusterAware() {
+		return this.#isClusterAware;
+	}
+	/** Whether this device is the leader of its multi-room cluster. */
+	get isClusterLeader() {
+		return this.#isClusterLeader;
+	}
+	/** Current volume level (0.0 - 1.0). */
 	get volume() {
 		return this.#volume;
 	}
+	/** Whether volume control is available on this device. */
 	get volumeAvailable() {
 		return this.#volumeAvailable;
 	}
+	/** Volume capabilities (absolute, relative, both, or none). */
 	get volumeCapabilities() {
 		return this.#volumeCapabilities;
 	}
+	/** Whether the device is currently muted. */
+	get volumeMuted() {
+		return this.#volumeMuted;
+	}
 	#device;
 	#clients;
+	#keyboardAttributes;
+	#keyboardState;
 	#nowPlayingClientBundleIdentifier;
 	#nowPlayingSnapshot;
 	#outputDeviceUID;
 	#outputDevices = [];
+	#clusterID;
+	#clusterType;
+	#isClusterAware;
+	#isClusterLeader;
 	#volume;
 	#volumeAvailable;
 	#volumeCapabilities;
+	#volumeMuted;
+	/**
+	* Creates a new AirPlayState tracker.
+	*
+	* @param device - The AirPlay device to track state for.
+	*/
 	constructor(device) {
 		super();
 		this.#device = device;
 		this.clear();
+		this.onConfigureConnection = this.onConfigureConnection.bind(this);
+		this.onKeyboard = this.onKeyboard.bind(this);
 		this.onDeviceInfo = this.onDeviceInfo.bind(this);
 		this.onDeviceInfoUpdate = this.onDeviceInfoUpdate.bind(this);
 		this.onOriginClientProperties = this.onOriginClientProperties.bind(this);
@@ -592,6 +1085,7 @@ var state_default = class extends EventEmitter {
 		this.onRemoveClient = this.onRemoveClient.bind(this);
 		this.onRemovePlayer = this.onRemovePlayer.bind(this);
 		this.onSendCommandResult = this.onSendCommandResult.bind(this);
+		this.onSendLyricsEvent = this.onSendLyricsEvent.bind(this);
 		this.onSetArtwork = this.onSetArtwork.bind(this);
 		this.onSetDefaultSupportedCommands = this.onSetDefaultSupportedCommands.bind(this);
 		this.onSetNowPlayingClient = this.onSetNowPlayingClient.bind(this);
@@ -605,8 +1099,12 @@ var state_default = class extends EventEmitter {
 		this.onVolumeControlAvailability = this.onVolumeControlAvailability.bind(this);
 		this.onVolumeControlCapabilitiesDidChange = this.onVolumeControlCapabilitiesDidChange.bind(this);
 		this.onVolumeDidChange = this.onVolumeDidChange.bind(this);
+		this.onVolumeMutedDidChange = this.onVolumeMutedDidChange.bind(this);
 	}
+	/** Subscribes to all DataStream events to track device state. Called internally via symbol. */
 	[STATE_SUBSCRIBE_SYMBOL]() {
+		this.#dataStream.on("configureConnection", this.onConfigureConnection);
+		this.#dataStream.on("keyboard", this.onKeyboard);
 		this.#dataStream.on("deviceInfo", this.onDeviceInfo);
 		this.#dataStream.on("deviceInfoUpdate", this.onDeviceInfoUpdate);
 		this.#dataStream.on("originClientProperties", this.onOriginClientProperties);
@@ -614,6 +1112,7 @@ var state_default = class extends EventEmitter {
 		this.#dataStream.on("removeClient", this.onRemoveClient);
 		this.#dataStream.on("removePlayer", this.onRemovePlayer);
 		this.#dataStream.on("sendCommandResult", this.onSendCommandResult);
+		this.#dataStream.on("sendLyricsEvent", this.onSendLyricsEvent);
 		this.#dataStream.on("setArtwork", this.onSetArtwork);
 		this.#dataStream.on("setDefaultSupportedCommands", this.onSetDefaultSupportedCommands);
 		this.#dataStream.on("setNowPlayingClient", this.onSetNowPlayingClient);
@@ -627,10 +1126,14 @@ var state_default = class extends EventEmitter {
 		this.#dataStream.on("volumeControlAvailability", this.onVolumeControlAvailability);
 		this.#dataStream.on("volumeControlCapabilitiesDidChange", this.onVolumeControlCapabilitiesDidChange);
 		this.#dataStream.on("volumeDidChange", this.onVolumeDidChange);
+		this.#dataStream.on("volumeMutedDidChange", this.onVolumeMutedDidChange);
 	}
+	/** Unsubscribes from all DataStream events. Called internally via symbol. */
 	[STATE_UNSUBSCRIBE_SYMBOL]() {
 		const dataStream = this.#dataStream;
 		if (!dataStream) return;
+		dataStream.off("configureConnection", this.onConfigureConnection);
+		dataStream.off("keyboard", this.onKeyboard);
 		dataStream.off("deviceInfo", this.onDeviceInfo);
 		dataStream.off("deviceInfoUpdate", this.onDeviceInfoUpdate);
 		dataStream.off("originClientProperties", this.onOriginClientProperties);
@@ -638,6 +1141,7 @@ var state_default = class extends EventEmitter {
 		dataStream.off("removeClient", this.onRemoveClient);
 		dataStream.off("removePlayer", this.onRemovePlayer);
 		dataStream.off("sendCommandResult", this.onSendCommandResult);
+		dataStream.off("sendLyricsEvent", this.onSendLyricsEvent);
 		dataStream.off("setArtwork", this.onSetArtwork);
 		dataStream.off("setDefaultSupportedCommands", this.onSetDefaultSupportedCommands);
 		dataStream.off("setNowPlayingClient", this.onSetNowPlayingClient);
@@ -651,126 +1155,324 @@ var state_default = class extends EventEmitter {
 		dataStream.off("volumeControlAvailability", this.onVolumeControlAvailability);
 		dataStream.off("volumeControlCapabilitiesDidChange", this.onVolumeControlCapabilitiesDidChange);
 		dataStream.off("volumeDidChange", this.onVolumeDidChange);
+		dataStream.off("volumeMutedDidChange", this.onVolumeMutedDidChange);
 	}
+	/** Resets all state to initial/default values. Called on connect and reconnect. */
 	clear() {
 		this.#clients = {};
+		this.#keyboardAttributes = null;
+		this.#keyboardState = Proto.KeyboardState_Enum.Unknown;
 		this.#nowPlayingClientBundleIdentifier = null;
 		this.#nowPlayingSnapshot = null;
 		this.#outputDeviceUID = null;
 		this.#outputDevices = [];
+		this.#clusterID = null;
+		this.#clusterType = 0;
+		this.#isClusterAware = false;
+		this.#isClusterLeader = false;
 		this.#volume = 0;
 		this.#volumeAvailable = false;
 		this.#volumeCapabilities = Proto.VolumeCapabilities_Enum.None;
-	}
+		this.#volumeMuted = false;
+	}
+	/**
+	* Handles a ConfigureConnection message from the Apple TV.
+	*
+	* @param message - The configure connection message.
+	*/
+	onConfigureConnection(message) {
+		this.emit("configureConnection", message);
+	}
+	/**
+	* Handles keyboard state changes. Updates internal state and emits 'keyboard'.
+	*
+	* @param message - The keyboard message with state and attributes.
+	*/
+	onKeyboard(message) {
+		this.#keyboardState = message.state;
+		this.#keyboardAttributes = message.attributes ?? null;
+		this.emit("keyboard", message);
+	}
+	/**
+	* Handles initial device info. Updates output device UID and cluster info.
+	*
+	* @param message - The device info message.
+	*/
 	onDeviceInfo(message) {
-		this.#updateOutputDeviceUID(message);
+		this.#updateDeviceInfo(message);
 		this.emit("deviceInfo", message);
 	}
+	/**
+	* Handles device info updates (e.g. cluster changes). Updates output device UID and cluster info.
+	*
+	* @param message - The device info update message.
+	*/
 	onDeviceInfoUpdate(message) {
-		this.#updateOutputDeviceUID(message);
+		this.#updateDeviceInfo(message);
 		this.emit("deviceInfoUpdate", message);
 	}
+	/**
+	* Handles origin client properties updates.
+	*
+	* @param message - The origin client properties message.
+	*/
 	onOriginClientProperties(message) {
 		this.emit("originClientProperties", message);
 	}
+	/**
+	* Handles player client properties updates.
+	*
+	* @param message - The player client properties message.
+	*/
 	onPlayerClientProperties(message) {
 		this.emit("playerClientProperties", message);
 	}
+	/**
+	* Handles removal of a client (app). Clears the now-playing reference if
+	* the removed client was the active one.
+	*
+	* @param message - The remove client message.
+	*/
 	onRemoveClient(message) {
+		if (!message.client?.bundleIdentifier) return;
 		if (!(message.client.bundleIdentifier in this.#clients)) return;
 		const wasActive = this.#nowPlayingClientBundleIdentifier === message.client.bundleIdentifier;
 		delete this.#clients[message.client.bundleIdentifier];
 		if (wasActive) this.#nowPlayingClientBundleIdentifier = null;
 		this.emit("removeClient", message);
 		this.emit("clients", this.#clients);
-		if (wasActive) this.#emitNowPlayingChangedIfNeeded();
+		if (wasActive) {
+			this.#emitActivePlayerChanged();
+			this.#emitNowPlayingChangedIfNeeded();
+		}
 	}
+	/**
+	* Handles command result notifications from the Apple TV.
+	*
+	* @param message - The send command result message.
+	*/
 	onSendCommandResult(message) {
 		this.emit("sendCommandResult", message);
 	}
+	/**
+	* Handles lyrics events (time-synced lyrics updates).
+	*
+	* @param message - The lyrics event message.
+	*/
+	onSendLyricsEvent(message) {
+		if (message.event) this.emit("lyricsEvent", message.event, message.playerPath);
+	}
+	/**
+	* Handles artwork set notifications.
+	*
+	* @param message - The set artwork message.
+	*/
 	onSetArtwork(message) {
 		this.emit("setArtwork", message);
 	}
+	/**
+	* Handles default supported commands for a client. These serve as fallback
+	* commands when a player has no commands of its own.
+	*
+	* @param message - The set default supported commands message.
+	*/
 	onSetDefaultSupportedCommands(message) {
 		if (message.playerPath?.client?.bundleIdentifier && message.supportedCommands) this.#client(message.playerPath.client.bundleIdentifier, message.playerPath.client.displayName).setDefaultSupportedCommands(message.supportedCommands.supportedCommands);
 		this.emit("setDefaultSupportedCommands", message);
 	}
+	/**
+	* Handles the now-playing client changing (e.g. user switches app).
+	* Updates the active client reference and emits change events.
+	*
+	* @param message - The set now-playing client message.
+	*/
 	onSetNowPlayingClient(message) {
+		const oldBundleId = this.#nowPlayingClientBundleIdentifier;
 		this.#nowPlayingClientBundleIdentifier = message.client?.bundleIdentifier ?? null;
 		if (message.client?.bundleIdentifier && message.client?.displayName) this.#client(message.client.bundleIdentifier, message.client.displayName);
 		this.emit("setNowPlayingClient", message);
+		if (oldBundleId !== this.#nowPlayingClientBundleIdentifier) this.#emitActivePlayerChanged();
 		this.#emitNowPlayingChangedIfNeeded();
 	}
+	/**
+	* Handles the active player changing within a client (e.g. PiP player becomes active).
+	* Creates the player if needed and sets it as the active player.
+	*
+	* @param message - The set now-playing player message.
+	*/
 	onSetNowPlayingPlayer(message) {
 		if (message.playerPath?.client?.bundleIdentifier && message.playerPath?.player?.identifier) {
 			const client = this.#client(message.playerPath.client.bundleIdentifier, message.playerPath.client.displayName);
+			const oldActiveId = client.activePlayer?.identifier;
 			client.getOrCreatePlayer(message.playerPath.player.identifier, message.playerPath.player.displayName);
 			client.setActivePlayer(message.playerPath.player.identifier);
+			if (oldActiveId !== message.playerPath.player.identifier) this.#emitActivePlayerChanged();
 		}
 		this.emit("setNowPlayingPlayer", message);
 		this.#emitNowPlayingChangedIfNeeded();
 	}
+	/**
+	* Handles comprehensive state updates. Processes playback state, now-playing info,
+	* supported commands, and playback queue in a single message.
+	* Emits granular events for each changed aspect.
+	*
+	* @param message - The set state message.
+	*/
 	onSetState(message) {
-		const bundleIdentifier = message.playerPath.client.bundleIdentifier;
+		const bundleIdentifier = message.playerPath?.client?.bundleIdentifier;
+		if (!bundleIdentifier) return;
 		const client = this.#client(bundleIdentifier, message.displayName);
 		const playerIdentifier = message.playerPath?.player?.identifier || "MediaRemote-DefaultPlayer";
 		const player = client.getOrCreatePlayer(playerIdentifier, message.playerPath?.player?.displayName);
+		const isActiveClient = bundleIdentifier === this.#nowPlayingClientBundleIdentifier;
+		if (message.playbackState) {
+			const oldState = player.playbackState;
+			player.setPlaybackState(message.playbackState, message.playbackStateTimestamp);
+			if (isActiveClient && oldState !== player.playbackState) this.emit("playbackStateChanged", client, player, oldState, player.playbackState);
+		}
 		if (message.nowPlayingInfo) player.setNowPlayingInfo(message.nowPlayingInfo);
-		if (message.playbackState) player.setPlaybackState(message.playbackState, message.playbackStateTimestamp);
-		if (message.supportedCommands) player.setSupportedCommands(message.supportedCommands.supportedCommands);
-		if (message.playbackQueue) player.setPlaybackQueue(message.playbackQueue);
+		if (message.supportedCommands) {
+			player.setSupportedCommands(message.supportedCommands.supportedCommands);
+			if (isActiveClient) this.emit("supportedCommandsChanged", client, player, player.supportedCommands);
+		}
+		if (message.playbackQueue) {
+			player.setPlaybackQueue(message.playbackQueue);
+			if (isActiveClient) this.emit("playbackQueueChanged", client, player);
+		}
 		this.emit("setState", message);
-		if (bundleIdentifier === this.#nowPlayingClientBundleIdentifier) this.#emitNowPlayingChangedIfNeeded();
+		if (isActiveClient) this.#emitNowPlayingChangedIfNeeded();
 	}
+	/**
+	* Handles content item updates (metadata, artwork, lyrics changes for existing items).
+	*
+	* @param message - The update content item message.
+	*/
 	onUpdateContentItem(message) {
-		const bundleIdentifier = message.playerPath.client.bundleIdentifier;
-		const client = this.#client(bundleIdentifier, message.playerPath.client.displayName);
+		const bundleIdentifier = message.playerPath?.client?.bundleIdentifier;
+		if (!bundleIdentifier) return;
+		const client = this.#client(bundleIdentifier, message.playerPath?.client?.displayName ?? "");
 		const playerIdentifier = message.playerPath?.player?.identifier || "MediaRemote-DefaultPlayer";
 		const player = client.getOrCreatePlayer(playerIdentifier, message.playerPath?.player?.displayName);
 		for (const item of message.contentItems) player.updateContentItem(item);
 		this.emit("updateContentItem", message);
 		if (bundleIdentifier === this.#nowPlayingClientBundleIdentifier) this.#emitNowPlayingChangedIfNeeded();
 	}
+	/**
+	* Handles artwork updates for content items. Emits 'artworkChanged' if a client and player are active.
+	*
+	* @param message - The update content item artwork message.
+	*/
 	onUpdateContentItemArtwork(message) {
 		this.emit("updateContentItemArtwork", message);
-	}
+		const client = this.nowPlayingClient;
+		const player = client?.activePlayer;
+		if (client && player) this.emit("artworkChanged", client, player);
+	}
+	/**
+	* Handles player registration or update. Creates the player if it does not exist.
+	*
+	* @param message - The update player message.
+	*/
 	onUpdatePlayer(message) {
 		if (message.playerPath?.client?.bundleIdentifier && message.playerPath?.player?.identifier) this.#client(message.playerPath.client.bundleIdentifier, message.playerPath.client.displayName).getOrCreatePlayer(message.playerPath.player.identifier, message.playerPath.player.displayName);
 		this.emit("updatePlayer", message);
 	}
+	/**
+	* Handles player removal. Removes the player from its client and emits
+	* active player changed events if the removed player was active.
+	*
+	* @param message - The remove player message.
+	*/
 	onRemovePlayer(message) {
 		if (message.playerPath?.client?.bundleIdentifier && message.playerPath?.player?.identifier) {
 			const client = this.#clients[message.playerPath.client.bundleIdentifier];
 			if (client) client.removePlayer(message.playerPath.player.identifier);
 		}
 		this.emit("removePlayer", message);
-		if (message.playerPath?.client?.bundleIdentifier === this.#nowPlayingClientBundleIdentifier) this.#emitNowPlayingChangedIfNeeded();
+		if (message.playerPath?.client?.bundleIdentifier === this.#nowPlayingClientBundleIdentifier) {
+			this.#emitActivePlayerChanged();
+			this.#emitNowPlayingChangedIfNeeded();
+		}
 	}
+	/**
+	* Handles client (app) registration or display name update.
+	*
+	* @param message - The update client message.
+	*/
 	onUpdateClient(message) {
+		if (!message.client?.bundleIdentifier) return;
 		this.#client(message.client.bundleIdentifier, message.client.displayName);
+		this.emit("updateClient", message);
 		this.emit("clients", this.#clients);
 	}
+	/**
+	* Handles output device list updates. Prefers cluster-aware devices when available.
+	*
+	* @param message - The update output device message.
+	*/
 	onUpdateOutputDevice(message) {
-		this.#outputDevices = message.outputDevices;
+		this.#outputDevices = message.clusterAwareOutputDevices?.length > 0 ? message.clusterAwareOutputDevices : message.outputDevices;
 		this.emit("updateOutputDevice", message);
 	}
+	/**
+	* Handles volume control availability changes.
+	*
+	* @param message - The volume control availability message.
+	*/
 	onVolumeControlAvailability(message) {
 		this.#volumeAvailable = message.volumeControlAvailable;
 		this.#volumeCapabilities = message.volumeCapabilities;
 		this.emit("volumeControlAvailability", message.volumeControlAvailable, message.volumeCapabilities);
 	}
+	/**
+	* Handles volume capabilities changes (e.g. device gains or loses absolute volume support).
+	*
+	* @param message - The volume capabilities change message.
+	*/
 	onVolumeControlCapabilitiesDidChange(message) {
+		if (!message.capabilities) return;
 		this.#volumeAvailable = message.capabilities.volumeControlAvailable;
 		this.#volumeCapabilities = message.capabilities.volumeCapabilities;
 		this.emit("volumeControlCapabilitiesDidChange", message.capabilities.volumeControlAvailable, message.capabilities.volumeCapabilities);
 	}
+	/**
+	* Handles volume level changes.
+	*
+	* @param message - The volume change message.
+	*/
 	onVolumeDidChange(message) {
 		this.#volume = message.volume;
 		this.emit("volumeDidChange", message.volume);
 	}
-	#updateOutputDeviceUID(message) {
+	/**
+	* Handles mute state changes.
+	*
+	* @param message - The volume muted change message.
+	*/
+	onVolumeMutedDidChange(message) {
+		this.#volumeMuted = message.isMuted;
+		this.emit("volumeMutedDidChange", this.#volumeMuted);
+	}
+	/**
+	* Extracts output device UID and cluster information from a device info message.
+	*
+	* @param message - The device info message.
+	*/
+	#updateDeviceInfo(message) {
 		this.#outputDeviceUID = message.clusterID || message.deviceUID || message.uniqueIdentifier || null;
-	}
+		this.#clusterID = message.clusterID || null;
+		this.#clusterType = message.clusterType ?? 0;
+		this.#isClusterAware = message.isClusterAware ?? false;
+		this.#isClusterLeader = message.isClusterLeader ?? false;
+	}
+	/**
+	* Gets or creates a Client for the given bundle identifier.
+	* Updates the display name if the client already exists.
+	*
+	* @param bundleIdentifier - The app's bundle identifier.
+	* @param displayName - The app's display name.
+	* @returns The existing or newly created Client.
+	*/
 	#client(bundleIdentifier, displayName) {
 		if (bundleIdentifier in this.#clients) {
 			const client = this.#clients[bundleIdentifier];
@@ -783,6 +1485,11 @@ var state_default = class extends EventEmitter {
 			return client;
 		}
 	}
+	/**
+	* Creates a snapshot of the current now-playing state for change detection.
+	*
+	* @returns A NowPlayingSnapshot of the current state.
+	*/
 	#createNowPlayingSnapshot() {
 		const client = this.nowPlayingClient;
 		const player = client?.activePlayer ?? null;
@@ -795,6 +1502,7 @@ var state_default = class extends EventEmitter {
 			album: player?.album ?? "",
 			genre: player?.genre ?? "",
 			duration: player?.duration ?? 0,
+			playbackRate: player?.playbackRate ?? 0,
 			shuffleMode: player?.shuffleMode ?? Proto.ShuffleMode_Enum.Unknown,
 			repeatMode: player?.repeatMode ?? Proto.RepeatMode_Enum.Unknown,
 			mediaType: player?.mediaType ?? Proto.ContentItemMetadata_MediaType.UnknownMediaType,
@@ -804,9 +1512,17 @@ var state_default = class extends EventEmitter {
 			contentIdentifier: player?.contentIdentifier ?? "",
 			artworkId: player?.artworkId ?? null,
 			hasArtworkUrl: player?.artworkUrl() != null,
-			hasArtworkData: player?.currentItemArtwork != null
+			hasArtworkData: player?.currentItemArtwork != null,
+			isAlwaysLive: player?.nowPlayingInfo?.isAlwaysLive ?? false,
+			isAdvertisement: player?.nowPlayingInfo?.isAdvertisement ?? false
 		};
 	}
+	/** Emits the 'activePlayerChanged' event with the current client and player. */
+	#emitActivePlayerChanged() {
+		const client = this.nowPlayingClient;
+		this.emit("activePlayerChanged", client, client?.activePlayer ?? null);
+	}
+	/** Emits 'nowPlayingChanged' only if the now-playing snapshot has actually changed. */
 	#emitNowPlayingChangedIfNeeded() {
 		const snapshot = this.#createNowPlayingSnapshot();
 		const previous = this.#nowPlayingSnapshot;
@@ -815,25 +1531,51 @@ var state_default = class extends EventEmitter {
 		const client = this.nowPlayingClient;
 		this.emit("nowPlayingChanged", client, client?.activePlayer ?? null);
 	}
+	/**
+	* Compares two NowPlayingSnapshot instances field-by-field for equality.
+	*
+	* @param a - First snapshot.
+	* @param b - Second snapshot.
+	* @returns True if all fields are equal.
+	*/
 	#snapshotsEqual(a, b) {
-		return a.bundleIdentifier === b.bundleIdentifier && a.playerIdentifier === b.playerIdentifier && a.playbackState === b.playbackState && a.title === b.title && a.artist === b.artist && a.album === b.album && a.genre === b.genre && a.duration === b.duration && a.shuffleMode === b.shuffleMode && a.repeatMode === b.repeatMode && a.mediaType === b.mediaType && a.seriesName === b.seriesName && a.seasonNumber === b.seasonNumber && a.episodeNumber === b.episodeNumber && a.contentIdentifier === b.contentIdentifier && a.artworkId === b.artworkId && a.hasArtworkUrl === b.hasArtworkUrl && a.hasArtworkData === b.hasArtworkData;
+		return a.bundleIdentifier === b.bundleIdentifier && a.playerIdentifier === b.playerIdentifier && a.playbackState === b.playbackState && a.title === b.title && a.artist === b.artist && a.album === b.album && a.genre === b.genre && a.duration === b.duration && a.playbackRate === b.playbackRate && a.shuffleMode === b.shuffleMode && a.repeatMode === b.repeatMode && a.mediaType === b.mediaType && a.seriesName === b.seriesName && a.seasonNumber === b.seasonNumber && a.episodeNumber === b.episodeNumber && a.contentIdentifier === b.contentIdentifier && a.artworkId === b.artworkId && a.hasArtworkUrl === b.hasArtworkUrl && a.hasArtworkData === b.hasArtworkData && a.isAlwaysLive === b.isAlwaysLive && a.isAdvertisement === b.isAdvertisement;
 	}
 };
 
 //#endregion
 //#region src/airplay/volume.ts
+/** Volume adjustment step size as a fraction (0.05 = 5%). */
 const VOLUME_STEP = .05;
+/**
+* Smart volume controller for an AirPlay device.
+* Automatically chooses between absolute volume (set a specific level) and
+* relative volume (HID volume up/down keys) based on the device's reported capabilities.
+*/
 var volume_default = class {
+	/** @returns The underlying AirPlay Protocol instance. */
 	get #protocol() {
 		return this.#device[PROTOCOL];
 	}
+	/** @returns The AirPlay state for volume and capability information. */
 	get #state() {
 		return this.#device.state;
 	}
 	#device;
+	/**
+	* Creates a new Volume controller.
+	*
+	* @param device - The AirPlay device to control volume for.
+	*/
 	constructor(device) {
 		this.#device = device;
 	}
+	/**
+	* Decreases the volume by one step. Uses absolute volume when available,
+	* falls back to HID relative volume keys otherwise.
+	*
+	* @throws CommandError when volume control is not available.
+	*/
 	async down() {
 		switch (this.#state.volumeCapabilities) {
 			case Proto.VolumeCapabilities_Enum.Absolute:
@@ -844,31 +1586,49 @@ var volume_default = class {
 			case Proto.VolumeCapabilities_Enum.Relative:
 				await this.#device.remote.volumeDown();
 				break;
-			default: throw new Error("Volume control is not available.");
+			default: throw new CommandError("Volume control is not available.");
 		}
 	}
+	/**
+	* Increases the volume by one step. Uses absolute volume when available,
+	* falls back to HID relative volume keys otherwise.
+	*
+	* @throws CommandError when volume control is not available.
+	*/
 	async up() {
 		switch (this.#state.volumeCapabilities) {
 			case Proto.VolumeCapabilities_Enum.Absolute:
 			case Proto.VolumeCapabilities_Enum.Both:
-				const newVolume = Math.max(0, this.#state.volume + VOLUME_STEP);
+				const newVolume = Math.min(1, Math.max(0, this.#state.volume + VOLUME_STEP));
 				await this.set(newVolume);
 				break;
 			case Proto.VolumeCapabilities_Enum.Relative:
 				await this.#device.remote.volumeUp();
 				break;
-			default: throw new Error("Volume control is not available.");
+			default: throw new CommandError("Volume control is not available.");
 		}
 	}
+	/**
+	* Fetches the current volume level from the device.
+	*
+	* @returns The volume level as a float between 0.0 and 1.0.
+	* @throws CommandError when no output device is active or the request fails.
+	*/
 	async get() {
-		if (!this.#state.outputDeviceUID) throw new Error("No output device active.");
+		if (!this.#state.outputDeviceUID) throw new CommandError("No output device active.");
 		const response = await this.#protocol.dataStream.exchange(DataStreamMessage.getVolume(this.#state.outputDeviceUID));
 		if (response.type === Proto.ProtocolMessage_Type.GET_VOLUME_RESULT_MESSAGE) return DataStreamMessage.getExtension(response, Proto.getVolumeResultMessage).volume;
-		throw new Error("Failed to get volume.");
-	}
+		throw new CommandError("Failed to get volume.");
+	}
+	/**
+	* Sets the volume to an absolute level.
+	*
+	* @param volume - The desired volume level (clamped to 0.0 - 1.0).
+	* @throws CommandError when no output device is active or absolute volume is not supported.
+	*/
 	async set(volume) {
-		if (!this.#state.outputDeviceUID) throw new Error("No output device active.");
-		if (![Proto.VolumeCapabilities_Enum.Absolute, Proto.VolumeCapabilities_Enum.Both].includes(this.#state.volumeCapabilities)) throw new Error("Absolute volume control is not available.");
+		if (!this.#state.outputDeviceUID) throw new CommandError("No output device active.");
+		if (![Proto.VolumeCapabilities_Enum.Absolute, Proto.VolumeCapabilities_Enum.Both].includes(this.#state.volumeCapabilities)) throw new CommandError("Absolute volume control is not available.");
 		volume = Math.min(1, Math.max(0, volume));
 		this.#protocol.context.logger.info(`Setting volume to ${volume} for device ${this.#state.outputDeviceUID}`);
 		await this.#protocol.dataStream.exchange(DataStreamMessage.setVolume(this.#state.outputDeviceUID, volume));
@@ -877,31 +1637,68 @@ var volume_default = class {
 
 //#endregion
 //#region src/airplay/device.ts
+/**
+* High-level abstraction for an AirPlay device (Apple TV or HomePod).
+* Manages the full lifecycle: connect, pair/verify, set up control/data/event streams,
+* and provides access to Remote, State, and Volume controllers.
+* Supports both transient (PIN-less) and credential-based pairing.
+*/
 var device_default = class extends EventEmitter {
+	/** @returns The underlying AirPlay Protocol instance (accessed via symbol for internal use). */
 	get [PROTOCOL]() {
 		return this.#protocol;
 	}
+	/** The mDNS discovery result used to connect to this device. */
 	get discoveryResult() {
 		return this.#discoveryResult;
 	}
+	/** Updates the discovery result, e.g. when the device's address changes. */
 	set discoveryResult(discoveryResult) {
 		this.#discoveryResult = discoveryResult;
 	}
+	/**
+	* Device capabilities derived from the AirPlay feature flags.
+	* Indicates which protocols and features the receiver supports.
+	*/
+	get capabilities() {
+		const has = (f) => this.#protocol?.hasReceiverFeature(f) ?? false;
+		return {
+			supportsAudio: has(AirPlayFeature.SupportsAirPlayAudio),
+			supportsBufferedAudio: has(AirPlayFeature.SupportsBufferedAudio),
+			supportsPTP: has(AirPlayFeature.SupportsPTP),
+			supportsRFC2198Redundancy: has(AirPlayFeature.SupportsRFC2198Redundancy),
+			supportsHangdogRemoteControl: has(AirPlayFeature.SupportsHangdogRemoteControl),
+			supportsUnifiedMediaControl: has(AirPlayFeature.SupportsUnifiedMediaControl),
+			supportsTransientPairing: has(AirPlayFeature.SupportsHKPairingAndAccessControl),
+			supportsSystemPairing: has(AirPlayFeature.SupportsSystemPairing),
+			supportsCoreUtilsPairing: has(AirPlayFeature.SupportsCoreUtilsPairingAndEncryption)
+		};
+	}
+	/** Whether the control stream TCP connection is currently active. */
 	get isConnected() {
 		return this.#protocol?.controlStream?.isConnected ?? false;
 	}
+	/** Raw receiver info dictionary from the /info endpoint, or undefined before connect. */
+	get receiverInfo() {
+		return this.#protocol?.receiverInfo;
+	}
+	/** The Remote controller for HID keys, SendCommand, text input, and touch. */
 	get remote() {
 		return this.#remote;
 	}
+	/** The State tracker for now-playing, volume, keyboard, and output device state. */
 	get state() {
 		return this.#state;
 	}
+	/** The Volume controller for absolute and relative volume adjustments. */
 	get volume() {
 		return this.#volume;
 	}
+	/** The shared PTP timing server, if one is assigned for multi-room sync. */
 	get timingServer() {
 		return this.#timingServer;
 	}
+	/** Assigns a PTP timing server for multi-room audio synchronization. */
 	set timingServer(timingServer) {
 		this.#timingServer = timingServer;
 	}
@@ -911,25 +1708,53 @@ var device_default = class extends EventEmitter {
 	#credentials;
 	#disconnect = false;
 	#discoveryResult;
+	#identity;
 	#feedbackInterval;
 	#keys;
+	#playUrlProtocol;
+	#prevDataStream;
+	#prevEventStream;
 	#protocol;
 	#timingServer;
-	constructor(discoveryResult) {
+	/**
+	* Creates a new AirPlayDevice.
+	*
+	* @param discoveryResult - The mDNS discovery result for the target device.
+	* @param identity - Optional partial device identity to present during pairing.
+	*/
+	constructor(discoveryResult, identity) {
 		super();
 		this.#discoveryResult = discoveryResult;
+		this.#identity = identity;
 		this.#remote = new remote_default(this);
 		this.#state = new state_default(this);
+		this.onClose = this.onClose.bind(this);
+		this.onError = this.onError.bind(this);
+		this.onTimeout = this.onTimeout.bind(this);
 		this.#volume = new volume_default(this);
 	}
+	/**
+	* Connects to the AirPlay device, performs pairing/verification,
+	* and sets up all streams (control, data, event). Emits 'connected' on success.
+	* If credentials are set, uses pair-verify; otherwise uses transient pairing.
+	*/
 	async connect() {
+		if (this.#protocol) {
+			this.#protocol.controlStream.off("close", this.onClose);
+			this.#protocol.controlStream.off("error", this.onError);
+			this.#protocol.controlStream.off("timeout", this.onTimeout);
+			try {
+				this.#protocol.disconnect();
+			} catch {}
+		}
 		this.#disconnect = false;
 		this.#state.clear();
-		this.#protocol = new Protocol(this.#discoveryResult);
-		this.#protocol.controlStream.on("close", this.#onClose.bind(this));
-		this.#protocol.controlStream.on("error", this.#onError.bind(this));
-		this.#protocol.controlStream.on("timeout", this.#onTimeout.bind(this));
+		this.#protocol = new Protocol(this.#discoveryResult, this.#identity);
+		this.#protocol.controlStream.on("close", this.onClose);
+		this.#protocol.controlStream.on("error", this.onError);
+		this.#protocol.controlStream.on("timeout", this.onTimeout);
 		await this.#protocol.connect();
+		await this.#protocol.fetchInfo();
 		if (this.#credentials) this.#keys = await this.#protocol.verify.start(this.#credentials);
 		else {
 			await this.#protocol.pairing.start();
@@ -938,15 +1763,19 @@ var device_default = class extends EventEmitter {
 		await this.#setup();
 		this.emit("connected");
 	}
+	/** Gracefully disconnects from the device, clears intervals, and tears down all streams. */
 	disconnect() {
 		this.#disconnect = true;
 		if (this.#feedbackInterval) {
 			clearInterval(this.#feedbackInterval);
 			this.#feedbackInterval = void 0;
 		}
+		this.#cleanupPlayUrl();
 		this.#unsubscribe();
 		this.#protocol.disconnect();
+		this.emit("disconnected", false);
 	}
+	/** Disconnects gracefully, swallowing any errors during cleanup. */
 	disconnectSafely() {
 		try {
 			this.disconnect();
@@ -954,27 +1783,128 @@ var device_default = class extends EventEmitter {
 			this.#protocol?.context?.logger?.warn("[device]", "Error during safe disconnect", err);
 		}
 	}
+	/**
+	* Enables or disables conversation detection on the output device (HomePod feature).
+	*
+	* @param enabled - Whether to enable conversation detection.
+	* @throws Error when no output device is active.
+	*/
+	async setConversationDetectionEnabled(enabled) {
+		const outputDeviceUID = this.#state.outputDeviceUID;
+		if (!outputDeviceUID) throw new Error("No output device active.");
+		await this.#protocol.dataStream.send(DataStreamMessage.setConversationDetectionEnabled(enabled, outputDeviceUID));
+	}
+	/**
+	* Adds devices to the current multi-room output context.
+	*
+	* @param deviceUIDs - UIDs of the devices to add.
+	*/
 	async addOutputDevices(deviceUIDs) {
 		await this.#protocol.dataStream.exchange(DataStreamMessage.modifyOutputContext(deviceUIDs));
 	}
+	/**
+	* Removes devices from the current multi-room output context.
+	*
+	* @param deviceUIDs - UIDs of the devices to remove.
+	*/
 	async removeOutputDevices(deviceUIDs) {
 		await this.#protocol.dataStream.exchange(DataStreamMessage.modifyOutputContext([], deviceUIDs));
 	}
+	/**
+	* Replaces the entire multi-room output context with the given devices.
+	*
+	* @param deviceUIDs - UIDs of the devices to set as the output context.
+	*/
 	async setOutputDevices(deviceUIDs) {
 		await this.#protocol.dataStream.exchange(DataStreamMessage.modifyOutputContext([], [], deviceUIDs));
 	}
+	/**
+	* Plays a URL on the device (the device fetches and plays the content).
+	* Creates a separate Protocol instance to avoid conflicting with the
+	* existing remote control session, following the same approach as pyatv.
+	*
+	* @param url - The media URL to play.
+	* @param position - Start position in seconds (defaults to 0).
+	* @throws Error when not connected.
+	*/
+	async playUrl(url, position = 0) {
+		if (!this.#keys) throw new Error("Not connected. Call connect() first.");
+		this.#playUrlProtocol?.disconnect();
+		const playProtocol = new Protocol(this.#discoveryResult, this.#identity);
+		if (this.#timingServer) playProtocol.useTimingServer(this.#timingServer);
+		try {
+			await playProtocol.connect();
+			await playProtocol.fetchInfo();
+			let keys;
+			if (this.#credentials) keys = await playProtocol.verify.start(this.#credentials);
+			else {
+				await playProtocol.pairing.start();
+				keys = await playProtocol.pairing.transient();
+			}
+			playProtocol.controlStream.enableEncryption(keys.accessoryToControllerKey, keys.controllerToAccessoryKey);
+			this.#playUrlProtocol = playProtocol;
+			await playProtocol.playUrl(url, keys.sharedSecret, keys.pairingId, position);
+		} catch (err) {
+			if (this.#playUrlProtocol !== playProtocol) playProtocol.disconnect();
+			throw err;
+		}
+	}
+	/** Waits for the current URL playback to finish, then cleans up the play URL protocol. */
+	async waitForPlaybackEnd() {
+		if (!this.#playUrlProtocol) return;
+		try {
+			await this.#playUrlProtocol.waitForPlaybackEnd();
+		} finally {
+			this.#cleanupPlayUrl();
+		}
+	}
+	/** Stops the current URL playback and cleans up the dedicated play URL protocol. */
+	stopPlayUrl() {
+		this.#cleanupPlayUrl();
+	}
+	/** Stops, disconnects, and discards the dedicated play URL protocol instance. */
+	#cleanupPlayUrl() {
+		if (this.#playUrlProtocol) {
+			this.#playUrlProtocol.stopPlayUrl();
+			this.#playUrlProtocol.disconnect();
+			this.#playUrlProtocol = void 0;
+		}
+	}
+	/**
+	* Streams audio from a source to the device via RAOP/RTP.
+	*
+	* @param source - The audio source to stream (e.g. MP3, WAV, URL, live).
+	*/
 	async streamAudio(source) {
 		await this.#protocol.setupAudioStream(source);
 	}
+	/**
+	* Requests the playback queue from the device.
+	*
+	* @param length - Maximum number of queue items to retrieve.
+	*/
 	async requestPlaybackQueue(length) {
 		await this.#protocol.dataStream.exchange(DataStreamMessage.playbackQueueRequest(0, length));
 	}
+	/**
+	* Sends a raw MRP command to the device via the DataStream.
+	*
+	* @param command - The command to send.
+	* @param options - Optional command options.
+	*/
 	async sendCommand(command, options) {
 		await this.#protocol.dataStream.exchange(DataStreamMessage.sendCommand(command, options));
 	}
+	/**
+	* Sets the pairing credentials for pair-verify authentication.
+	* Must be called before connect() if credential-based pairing is desired.
+	*
+	* @param credentials - The accessory credentials obtained from pair-setup.
+	*/
 	setCredentials(credentials) {
 		this.#credentials = credentials;
 	}
+	/** Sends a periodic feedback request to keep the AirPlay session alive. */
 	async #feedback() {
 		try {
 			await this.#protocol.feedback();
@@ -982,37 +1912,55 @@ var device_default = class extends EventEmitter {
 			this.#protocol.context.logger.error("Feedback error", err);
 		}
 	}
-	#onClose() {
-		this.#protocol.context.logger.net("#onClose() called on airplay device.");
-		if (!this.#disconnect) {
-			this.disconnectSafely();
-			this.emit("disconnected", true);
-		} else this.emit("disconnected", false);
-	}
-	#onError(err) {
+	/** Handles the control stream close event. Emits 'disconnected' with unexpected=true if not intentional. */
+	onClose() {
+		this.#protocol.context.logger.net("onClose() called on airplay device.");
+		if (this.#disconnect) return;
+		this.#disconnect = true;
+		this.disconnectSafely();
+		this.emit("disconnected", true);
+	}
+	/**
+	* Handles stream error events by logging them.
+	*
+	* @param err - The error that occurred.
+	*/
+	onError(err) {
 		this.#protocol.context.logger.error("AirPlay error", err);
 	}
-	#onTimeout() {
+	/** Handles stream timeout events by destroying the control stream. */
+	onTimeout() {
 		this.#protocol.context.logger.error("AirPlay timeout");
 		this.#protocol.controlStream.destroy();
 	}
+	/**
+	* Sets up encryption, event/data streams, feedback interval, and initial state subscriptions.
+	* Called after successful pairing/verification.
+	*/
 	async #setup() {
 		const keys = this.#keys;
 		this.#protocol.controlStream.enableEncryption(keys.accessoryToControllerKey, keys.controllerToAccessoryKey);
 		this.#unsubscribe();
 		if (this.#timingServer) this.#protocol.useTimingServer(this.#timingServer);
 		try {
+			this.#prevDataStream?.off("error", this.onError);
+			this.#prevDataStream?.off("timeout", this.onTimeout);
+			this.#prevEventStream?.off("error", this.onError);
+			this.#prevEventStream?.off("timeout", this.onTimeout);
 			await this.#protocol.setupEventStream(keys.sharedSecret, keys.pairingId);
 			await this.#protocol.setupDataStream(keys.sharedSecret, () => this.#subscribe());
-			this.#protocol.dataStream.on("error", this.#onError.bind(this));
-			this.#protocol.dataStream.on("timeout", this.#onTimeout.bind(this));
-			this.#protocol.eventStream.on("error", this.#onError.bind(this));
-			this.#protocol.eventStream.on("timeout", this.#onTimeout.bind(this));
+			this.#protocol.dataStream.on("error", this.onError);
+			this.#protocol.dataStream.on("timeout", this.onTimeout);
+			this.#protocol.eventStream.on("error", this.onError);
+			this.#protocol.eventStream.on("timeout", this.onTimeout);
+			this.#prevDataStream = this.#protocol.dataStream;
+			this.#prevEventStream = this.#protocol.eventStream;
 			if (this.#feedbackInterval) clearInterval(this.#feedbackInterval);
 			this.#feedbackInterval = setInterval(async () => await this.#feedback(), FEEDBACK_INTERVAL);
-			await this.#protocol.dataStream.exchange(DataStreamMessage.deviceInfo(keys.pairingId));
+			await this.#protocol.dataStream.exchange(DataStreamMessage.deviceInfo(keys.pairingId, this.#protocol.context.identity));
 			await this.#protocol.dataStream.exchange(DataStreamMessage.setConnectionState());
-			await this.#protocol.dataStream.exchange(DataStreamMessage.clientUpdatesConfig());
+			await this.#protocol.dataStream.exchange(DataStreamMessage.clientUpdatesConfig(true, true, true, true, true, true));
+			await this.#protocol.dataStream.exchange(DataStreamMessage.getState());
 			this.#protocol.context.logger.info("Protocol ready.");
 		} catch (err) {
 			if (this.#feedbackInterval) {
@@ -1024,9 +1972,11 @@ var device_default = class extends EventEmitter {
 			throw err;
 		}
 	}
+	/** Subscribes the state tracker to DataStream events. */
 	#subscribe() {
 		this.#state[STATE_SUBSCRIBE_SYMBOL]();
 	}
+	/** Unsubscribes the state tracker from DataStream events. */
 	#unsubscribe() {
 		try {
 			this.#state[STATE_UNSUBSCRIBE_SYMBOL]();
@@ -1038,109 +1988,640 @@ var device_default = class extends EventEmitter {
 
 //#endregion
 //#region src/companion-link/const.ts
+/** Symbol used to access the underlying Companion Link Protocol instance from a CompanionLinkDevice. */
 const PROTOCOL$1 = Symbol("com.basmilius.companion-link:protocol");
 
+//#endregion
+//#region src/companion-link/state.ts
+/** Default text input state when no text input session is active. */
+const DEFAULT_TEXT_INPUT = {
+	isActive: false,
+	documentText: "",
+	isSecure: false,
+	keyboardType: 0,
+	autocorrection: false,
+	autocapitalization: false
+};
+/**
+* Tracks the state of a Companion Link device: attention state, media controls,
+* now-playing info, supported actions, text input, and volume availability.
+* Subscribes to protocol stream events and emits typed state change events.
+*/
+var CompanionLinkState = class extends EventEmitter {
+	/** Current attention state of the device (active, idle, screensaver, etc.). */
+	get attentionState() {
+		return this.#attentionState;
+	}
+	/** Parsed media capabilities indicating which controls are available. */
+	get mediaCapabilities() {
+		return this.#mediaCapabilities;
+	}
+	/** Raw media control flags bitmask from the device. */
+	get mediaControlFlags() {
+		return this.#mediaControlFlags;
+	}
+	/** Current now-playing info as a key-value dictionary, or null. */
+	get nowPlayingInfo() {
+		return this.#nowPlayingInfo;
+	}
+	/** Currently supported actions dictionary, or null. */
+	get supportedActions() {
+		return this.#supportedActions;
+	}
+	/** Current text input session state. */
+	get textInputState() {
+		return this.#textInputState;
+	}
+	/** Whether volume control is currently available via the Companion Link protocol. */
+	get volumeAvailable() {
+		return this.#volumeAvailable;
+	}
+	#protocol;
+	#attentionState = "unknown";
+	#mediaCapabilities = parseMediaControlFlags(0);
+	#mediaControlFlags = 0;
+	#nowPlayingInfo = null;
+	#supportedActions = null;
+	#textInputState = { ...DEFAULT_TEXT_INPUT };
+	#volumeAvailable = false;
+	/**
+	* Creates a new CompanionLinkState tracker.
+	*
+	* @param protocol - The Companion Link protocol instance to observe.
+	*/
+	constructor(protocol) {
+		super();
+		this.#protocol = protocol;
+		this.onMediaControl = this.onMediaControl.bind(this);
+		this.onSystemStatus = this.onSystemStatus.bind(this);
+		this.onTVSystemStatus = this.onTVSystemStatus.bind(this);
+		this.onNowPlayingInfo = this.onNowPlayingInfo.bind(this);
+		this.onSupportedActions = this.onSupportedActions.bind(this);
+		this.onTextInputStarted = this.onTextInputStarted.bind(this);
+		this.onTextInputStopped = this.onTextInputStopped.bind(this);
+	}
+	/** Subscribes to protocol stream events and registers interests for push notifications. */
+	subscribe() {
+		const stream = this.#protocol.stream;
+		stream.on("_iMC", this.onMediaControl);
+		stream.on("SystemStatus", this.onSystemStatus);
+		stream.on("TVSystemStatus", this.onTVSystemStatus);
+		stream.on("NowPlayingInfo", this.onNowPlayingInfo);
+		stream.on("SupportedActions", this.onSupportedActions);
+		stream.on("_tiStarted", this.onTextInputStarted);
+		stream.on("_tiStopped", this.onTextInputStopped);
+		this.#protocol.registerInterests(["_iMC"]);
+		this.#protocol.registerInterests(["SystemStatus"]);
+		this.#protocol.registerInterests(["TVSystemStatus"]);
+		this.#protocol.registerInterests(["NowPlayingInfo"]);
+		this.#protocol.registerInterests(["SupportedActions"]);
+	}
+	/** Unsubscribes from protocol stream events and deregisters interests. */
+	unsubscribe() {
+		const stream = this.#protocol.stream;
+		if (!stream.isConnected) return;
+		stream.off("_iMC", this.onMediaControl);
+		stream.off("SystemStatus", this.onSystemStatus);
+		stream.off("TVSystemStatus", this.onTVSystemStatus);
+		stream.off("NowPlayingInfo", this.onNowPlayingInfo);
+		stream.off("SupportedActions", this.onSupportedActions);
+		stream.off("_tiStarted", this.onTextInputStarted);
+		stream.off("_tiStopped", this.onTextInputStopped);
+		try {
+			this.#protocol.deregisterInterests(["_iMC"]);
+			this.#protocol.deregisterInterests(["SystemStatus"]);
+			this.#protocol.deregisterInterests(["TVSystemStatus"]);
+			this.#protocol.deregisterInterests(["NowPlayingInfo"]);
+			this.#protocol.deregisterInterests(["SupportedActions"]);
+		} catch {}
+	}
+	/** Fetches the initial attention state and media control status from the device. */
+	async fetchInitialState() {
+		try {
+			const state = await this.#protocol.getAttentionState();
+			this.#attentionState = state;
+			this.emit("attentionStateChanged", state);
+		} catch (err) {
+			this.#protocol.context.logger.warn("[cl-state]", "Failed to fetch initial attention state", err);
+		}
+		try {
+			await this.#protocol.fetchMediaControlStatus();
+		} catch (err) {
+			this.#protocol.context.logger.warn("[cl-state]", "Failed to fetch media control status", err);
+		}
+	}
+	/** Resets all state to initial/default values. */
+	clear() {
+		this.#attentionState = "unknown";
+		this.#mediaCapabilities = parseMediaControlFlags(0);
+		this.#mediaControlFlags = 0;
+		this.#nowPlayingInfo = null;
+		this.#supportedActions = null;
+		this.#textInputState = { ...DEFAULT_TEXT_INPUT };
+		this.#volumeAvailable = false;
+	}
+	/**
+	* Handles media control flag updates (_iMC). Parses the flags bitmask and
+	* emits events if capabilities or volume availability changed.
+	*
+	* @param data - The raw media control payload.
+	*/
+	onMediaControl(data) {
+		try {
+			const payload = data;
+			const flags = Number(payload?._mcF ?? 0);
+			if (flags !== this.#mediaControlFlags) {
+				this.#mediaControlFlags = flags;
+				this.#mediaCapabilities = parseMediaControlFlags(flags);
+				const wasVolumeAvailable = this.#volumeAvailable;
+				this.#volumeAvailable = this.#mediaCapabilities.volume;
+				this.emit("mediaControlFlagsChanged", flags, this.#mediaCapabilities);
+				if (wasVolumeAvailable !== this.#volumeAvailable) this.emit("volumeAvailabilityChanged", this.#volumeAvailable);
+			}
+		} catch (err) {
+			this.#protocol.context.logger.error("[cl-state]", "_iMC parse error", err);
+		}
+	}
+	/**
+	* Handles SystemStatus events (attention state changes from non-TV devices).
+	*
+	* @param data - The raw system status payload containing a state code.
+	*/
+	onSystemStatus(data) {
+		const state = convertAttentionState(data.state);
+		if (state !== this.#attentionState) {
+			this.#attentionState = state;
+			this.emit("attentionStateChanged", state);
+		}
+	}
+	/**
+	* Handles TVSystemStatus events (attention state changes from Apple TV).
+	*
+	* @param data - The raw TV system status payload containing a state code.
+	*/
+	onTVSystemStatus(data) {
+		const state = convertAttentionState(data.state);
+		if (state !== this.#attentionState) {
+			this.#attentionState = state;
+			this.emit("attentionStateChanged", state);
+		}
+	}
+	/**
+	* Handles NowPlayingInfo updates. Decodes the NSKeyedArchiver plist payload
+	* when present, otherwise uses the raw dictionary.
+	*
+	* @param data - The raw now-playing info payload.
+	*/
+	onNowPlayingInfo(data) {
+		try {
+			const payload = data;
+			if (payload?.NowPlayingInfoKey) {
+				const raw = payload.NowPlayingInfoKey;
+				const buf = Buffer.from(raw);
+				const plist = Plist.parse(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+				const decoded = NSKeyedArchiver.decode(plist);
+				this.#nowPlayingInfo = decoded && typeof decoded === "object" && !Array.isArray(decoded) ? decoded : null;
+			} else this.#nowPlayingInfo = payload ?? null;
+			this.emit("nowPlayingInfoChanged", this.#nowPlayingInfo);
+		} catch (err) {
+			this.#protocol.context.logger.error("[cl-state]", "NowPlayingInfo parse error", err);
+		}
+	}
+	/**
+	* Handles SupportedActions updates from the device.
+	*
+	* @param data - The raw supported actions payload.
+	*/
+	onSupportedActions(data) {
+		try {
+			const payload = data;
+			this.#supportedActions = payload ?? null;
+			this.emit("supportedActionsChanged", payload ?? {});
+		} catch (err) {
+			this.#protocol.context.logger.error("[cl-state]", "SupportedActions parse error", err);
+		}
+	}
+	/**
+	* Handles the start of a text input session. Parses the plist payload to extract
+	* document text, security mode, keyboard type, and autocorrection settings.
+	*
+	* @param data - The raw text input started payload.
+	*/
+	onTextInputStarted(data) {
+		try {
+			const payload = data;
+			let documentText = "";
+			let isSecure = false;
+			let keyboardType = 0;
+			let autocorrection = false;
+			let autocapitalization = false;
+			if (payload?._tiD) {
+				const plistData = Plist.parse(Buffer.from(payload._tiD).buffer);
+				documentText = plistData._tiDT ?? "";
+				isSecure = plistData._tiSR ?? false;
+				keyboardType = plistData._tiKT ?? 0;
+				autocorrection = plistData._tiAC ?? false;
+				autocapitalization = plistData._tiAP ?? false;
+			}
+			this.#textInputState = {
+				isActive: true,
+				documentText,
+				isSecure,
+				keyboardType,
+				autocorrection,
+				autocapitalization
+			};
+			this.emit("textInputChanged", this.#textInputState);
+		} catch (err) {
+			this.#protocol.context.logger.error("[cl-state]", "Text input started parse error", err);
+		}
+	}
+	/**
+	* Handles the end of a text input session. Resets the text input state to defaults.
+	*
+	* @param _data - The raw text input stopped payload (unused).
+	*/
+	onTextInputStopped(_data) {
+		this.#textInputState = { ...DEFAULT_TEXT_INPUT };
+		this.emit("textInputChanged", this.#textInputState);
+	}
+};
+/**
+* Parses a media control flags bitmask into a structured MediaCapabilities object.
+*
+* @param flags - The raw bitmask from the _iMC event.
+* @returns An object indicating which media controls are available.
+*/
+function parseMediaControlFlags(flags) {
+	return {
+		play: (flags & MediaControlFlag.Play) !== 0,
+		pause: (flags & MediaControlFlag.Pause) !== 0,
+		previousTrack: (flags & MediaControlFlag.PreviousTrack) !== 0,
+		nextTrack: (flags & MediaControlFlag.NextTrack) !== 0,
+		fastForward: (flags & MediaControlFlag.FastForward) !== 0,
+		rewind: (flags & MediaControlFlag.Rewind) !== 0,
+		volume: (flags & MediaControlFlag.Volume) !== 0,
+		skipForward: (flags & MediaControlFlag.SkipForward) !== 0,
+		skipBackward: (flags & MediaControlFlag.SkipBackward) !== 0
+	};
+}
+
 //#endregion
 //#region src/companion-link/device.ts
+/**
+* High-level abstraction for a Companion Link device (Apple TV).
+* Manages the OPack-based Companion Link protocol lifecycle: connect, pair-verify,
+* session setup, and provides access to HID buttons, app launching, user accounts,
+* media control, text input, touch, Siri, and system controls.
+* Requires credentials (obtained from pair-setup) to connect.
+*/
 var device_default$1 = class extends EventEmitter {
+	/** @returns The underlying Companion Link Protocol instance (accessed via symbol for internal use). */
 	get [PROTOCOL$1]() {
 		return this.#protocol;
 	}
+	/** The mDNS discovery result used to connect to this device. */
 	get discoveryResult() {
 		return this.#discoveryResult;
 	}
+	/** Updates the discovery result, e.g. when the device's address changes. */
 	set discoveryResult(discoveryResult) {
 		this.#discoveryResult = discoveryResult;
 	}
+	/** Whether the Companion Link stream is currently connected. */
 	get isConnected() {
 		return this.#protocol?.stream?.isConnected ?? false;
 	}
+	/** The state tracker for attention, media controls, now-playing, and text input. */
+	get state() {
+		return this.#state;
+	}
+	/** Current text input session state (convenience accessor). */
+	get textInputState() {
+		return this.#state.textInputState;
+	}
 	#credentials;
 	#disconnect = false;
 	#discoveryResult;
 	#heartbeatInterval;
 	#keys;
 	#protocol;
+	#state;
+	/**
+	* Creates a new CompanionLinkDevice.
+	*
+	* @param discoveryResult - The mDNS discovery result for the target device.
+	*/
 	constructor(discoveryResult) {
 		super();
 		this.#discoveryResult = discoveryResult;
-		this.onSystemStatus = this.onSystemStatus.bind(this);
-		this.onTVSystemStatus = this.onTVSystemStatus.bind(this);
-	}
+		this.onClose = this.onClose.bind(this);
+		this.onError = this.onError.bind(this);
+		this.onTimeout = this.onTimeout.bind(this);
+	}
+	/**
+	* Connects to the Companion Link device, performs pair-verify, and sets up
+	* all protocol sessions (system info, TVRC, touch, text input).
+	* Emits 'connected' on success.
+	*
+	* @throws CredentialsError when no credentials are set.
+	*/
 	async connect() {
-		if (!this.#credentials) throw new Error("Credentials are required to connect to a Companion Link device.");
+		if (!this.#credentials) throw new CredentialsError("Credentials are required to connect to a Companion Link device.");
+		if (this.#protocol) {
+			this.#protocol.stream.off("close", this.onClose);
+			this.#protocol.stream.off("error", this.onError);
+			this.#protocol.stream.off("timeout", this.onTimeout);
+		}
 		this.#disconnect = false;
 		this.#protocol = new Protocol$1(this.#discoveryResult);
-		this.#protocol.stream.on("close", async () => this.#onClose());
-		this.#protocol.stream.on("error", async (err) => this.#onError(err));
-		this.#protocol.stream.on("timeout", async () => this.#onTimeout());
+		this.#protocol.stream.on("close", this.onClose);
+		this.#protocol.stream.on("error", this.onError);
+		this.#protocol.stream.on("timeout", this.onTimeout);
 		await this.#protocol.connect();
 		this.#keys = await this.#protocol.verify.start(this.#credentials);
 		await this.#setup();
 		this.emit("connected");
 	}
+	/** Gracefully disconnects from the device, clears heartbeat interval, and unsubscribes from events. */
 	async disconnect() {
 		this.#disconnect = true;
 		if (this.#heartbeatInterval) {
 			clearInterval(this.#heartbeatInterval);
 			this.#heartbeatInterval = void 0;
 		}
-		await this.#unsubscribe();
+		this.#state?.unsubscribe();
 		await this.#protocol.disconnect();
 	}
+	/** Disconnects gracefully, swallowing any errors during cleanup. */
 	async disconnectSafely() {
 		try {
 			await this.disconnect();
-		} catch (_) {}
+		} catch {}
 	}
+	/**
+	* Sets the pairing credentials required for pair-verify authentication.
+	* Must be called before connect().
+	*
+	* @param credentials - The accessory credentials from pair-setup.
+	*/
 	async setCredentials(credentials) {
 		this.#credentials = credentials;
 	}
+	/**
+	* Fetches the current attention state of the device (active, idle, screensaver, etc.).
+	*
+	* @returns The current attention state.
+	*/
 	async getAttentionState() {
 		return await this.#protocol.getAttentionState();
 	}
+	/**
+	* Fetches the list of apps that can be launched on the device.
+	*
+	* @returns Array of launchable app descriptors.
+	*/
 	async getLaunchableApps() {
 		return await this.#protocol.getLaunchableApps();
 	}
+	/**
+	* Fetches the list of user accounts configured on the device.
+	*
+	* @returns Array of user account descriptors.
+	*/
 	async getUserAccounts() {
 		return await this.#protocol.getUserAccounts();
 	}
+	/**
+	* Fetches the current now-playing information from the device.
+	*
+	* @returns The now-playing info payload.
+	*/
+	async fetchNowPlayingInfo() {
+		return await this.#protocol.fetchNowPlayingInfo();
+	}
+	/**
+	* Fetches the currently supported actions from the device.
+	*
+	* @returns The supported actions payload.
+	*/
+	async fetchSupportedActions() {
+		return await this.#protocol.fetchSupportedActions();
+	}
+	/**
+	* Fetches the current media control status (available controls bitmask).
+	*
+	* @returns The media control status payload.
+	*/
+	async fetchMediaControlStatus() {
+		return await this.#protocol.fetchMediaControlStatus();
+	}
+	/**
+	* Launches an app on the device by its bundle identifier.
+	*
+	* @param bundleId - The bundle identifier of the app to launch.
+	*/
 	async launchApp(bundleId) {
 		await this.#protocol.launchApp(bundleId);
 	}
+	/**
+	* Opens a URL on the device (universal link or app-specific URL scheme).
+	*
+	* @param url - The URL to open.
+	*/
 	async launchUrl(url) {
 		await this.#protocol.launchUrl(url);
 	}
+	/**
+	* Sends a media control command (play, pause, next, etc.) via the Companion Link protocol.
+	*
+	* @param command - The media control command key.
+	* @param content - Optional additional content for the command.
+	*/
 	async mediaControlCommand(command, content) {
 		await this.#protocol.mediaControlCommand(command, content);
 	}
+	/**
+	* Sends a HID button press via the Companion Link protocol.
+	*
+	* @param command - The HID command key (e.g. 'up', 'select', 'menu').
+	* @param type - Optional press type (short, long, double).
+	* @param holdDelayMs - Optional hold duration in milliseconds for long presses.
+	*/
 	async pressButton(command, type, holdDelayMs) {
 		await this.#protocol.pressButton(command, type, holdDelayMs);
 	}
+	/**
+	* Switches to a different user account on the device.
+	*
+	* @param accountId - The ID of the user account to switch to.
+	*/
 	async switchUserAccount(accountId) {
 		await this.#protocol.switchUserAccount(accountId);
 	}
-	async #heartbeat() {
-		try {
-			this.#protocol.noOp();
-		} catch (err) {
-			this.#protocol.context.logger.error("Heartbeat error", err);
+	/**
+	* Sets the text input field to the given text, replacing any existing content.
+	*
+	* @param text - The text to set.
+	*/
+	async textSet(text) {
+		await this.#protocol.textInputCommand(text, true);
+	}
+	/**
+	* Appends text to the current text input field content.
+	*
+	* @param text - The text to append.
+	*/
+	async textAppend(text) {
+		await this.#protocol.textInputCommand(text, false);
+	}
+	/** Clears the text input field. */
+	async textClear() {
+		await this.#protocol.textInputCommand("", true);
+	}
+	/**
+	* Sends a raw touch event to the device.
+	*
+	* @param finger - Finger index (0-based).
+	* @param phase - Touch phase (0 = Began, 1 = Moved, 2 = Ended).
+	* @param x - Horizontal position.
+	* @param y - Vertical position.
+	*/
+	async sendTouchEvent(finger, phase, x, y) {
+		await this.#protocol.sendTouchEvent(finger, phase, x, y);
+	}
+	/**
+	* Simulates a tap at the given coordinates.
+	*
+	* @param x - Horizontal position (defaults to center 500).
+	* @param y - Vertical position (defaults to center 500).
+	*/
+	async tap(x = 500, y = 500) {
+		await this.sendTouchEvent(0, 0, x, y);
+		await waitFor(50);
+		await this.sendTouchEvent(0, 2, x, y);
+	}
+	/**
+	* Simulates a swipe gesture in the given direction.
+	*
+	* @param direction - Swipe direction.
+	* @param duration - Swipe duration in milliseconds (defaults to 200).
+	*/
+	async swipe(direction, duration = 200) {
+		const [startX, startY, endX, endY] = {
+			up: [
+				500,
+				700,
+				500,
+				300
+			],
+			down: [
+				500,
+				300,
+				500,
+				700
+			],
+			left: [
+				700,
+				500,
+				300,
+				500
+			],
+			right: [
+				300,
+				500,
+				700,
+				500
+			]
+		}[direction];
+		const steps = Math.max(4, Math.floor(duration / 50));
+		const deltaX = (endX - startX) / steps;
+		const deltaY = (endY - startY) / steps;
+		const stepDuration = duration / steps;
+		await this.sendTouchEvent(0, 0, startX, startY);
+		for (let i = 1; i < steps; i++) {
+			await waitFor(stepDuration);
+			await this.sendTouchEvent(0, 1, Math.round(startX + deltaX * i), Math.round(startY + deltaY * i));
 		}
-	}
-	async #onClose() {
-		this.#protocol.context.logger.net("#onClose() called on companion link device.");
-		if (!this.#disconnect) {
-			await this.disconnectSafely();
-			this.emit("disconnected", true);
-		} else this.emit("disconnected", false);
-	}
-	async #onError(err) {
-		this.#protocol.context.logger.error("Companion Link error", err);
-	}
-	async #onTimeout() {
-		this.#protocol.context.logger.error("Companion Link timeout");
-		await this.#protocol.stream.destroy();
-	}
+		await waitFor(stepDuration);
+		await this.sendTouchEvent(0, 2, endX, endY);
+	}
+	/** Toggles closed captions on the device. */
+	async toggleCaptions() {
+		await this.#protocol.toggleCaptions();
+	}
+	/**
+	* Toggles the system appearance between light and dark mode.
+	*
+	* @param light - True for light mode, false for dark mode.
+	*/
+	async toggleSystemAppearance(light) {
+		await this.#protocol.toggleSystemAppearance(light);
+	}
+	/**
+	* Enables or disables the "Reduce Loud Sounds" setting.
+	*
+	* @param enabled - Whether to enable the setting.
+	*/
+	async toggleReduceLoudSounds(enabled) {
+		await this.#protocol.toggleReduceLoudSounds(enabled);
+	}
+	/**
+	* Enables or disables finding mode (Find My integration).
+	*
+	* @param enabled - Whether to enable finding mode.
+	*/
+	async toggleFindingMode(enabled) {
+		await this.#protocol.toggleFindingMode(enabled);
+	}
+	/**
+	* Fetches the "Up Next" queue from the device.
+	*
+	* @param paginationToken - Optional token for paginated results.
+	* @returns The Up Next queue payload.
+	*/
+	async fetchUpNext(paginationToken) {
+		return await this.#protocol.fetchUpNext(paginationToken);
+	}
+	/**
+	* Adds an item to the "Up Next" queue.
+	*
+	* @param identifier - Content item identifier.
+	* @param kind - Content kind descriptor.
+	*/
+	async addToUpNext(identifier, kind) {
+		await this.#protocol.addToUpNext(identifier, kind);
+	}
+	/**
+	* Removes an item from the "Up Next" queue.
+	*
+	* @param identifier - Content item identifier.
+	* @param kind - Content kind descriptor.
+	*/
+	async removeFromUpNext(identifier, kind) {
+		await this.#protocol.removeFromUpNext(identifier, kind);
+	}
+	/**
+	* Marks a content item as watched.
+	*
+	* @param identifier - Content item identifier.
+	* @param kind - Content kind descriptor.
+	*/
+	async markAsWatched(identifier, kind) {
+		await this.#protocol.markAsWatched(identifier, kind);
+	}
+	/** Starts a Siri session on the device. */
+	async siriStart() {
+		await this.#protocol.siriStart();
+	}
+	/** Stops the active Siri session on the device. */
+	async siriStop() {
+		await this.#protocol.siriStop();
+	}
+	/**
+	* Sets up encryption, protocol sessions (system info, TVRC, touch, text input),
+	* heartbeat interval, and state tracking. Called after successful pair-verify.
+	*/
 	async #setup() {
 		const keys = this.#keys;
 		this.#protocol.stream.enableEncryption(keys.accessoryToControllerKey, keys.controllerToAccessoryKey);
@@ -1150,102 +2631,145 @@ var device_default$1 = class extends EventEmitter {
 			await this.#protocol.tvrcSessionStart();
 			await this.#protocol.touchStart();
 			await this.#protocol.tiStart();
-			await this.#protocol.subscribe("_iMC", (data) => {
-				this.emit("mediaControl", data);
-			});
-			this.#heartbeatInterval = setInterval(async () => await this.#heartbeat(), 15e3);
-			await this.#subscribe();
+			this.#heartbeatInterval = setInterval(() => {
+				try {
+					this.#protocol.noOp();
+				} catch (err) {
+					this.#protocol.context.logger.error("Heartbeat failed", err);
+				}
+			}, 15e3);
+			if (this.#state) this.#state.removeAllListeners();
+			this.#state = new CompanionLinkState(this.#protocol);
+			this.#state.on("attentionStateChanged", (s) => this.emit("attentionStateChanged", s));
+			this.#state.on("mediaControlFlagsChanged", (f, c) => this.emit("mediaControlFlagsChanged", f, c));
+			this.#state.on("nowPlayingInfoChanged", (i) => this.emit("nowPlayingInfoChanged", i));
+			this.#state.on("supportedActionsChanged", (a) => this.emit("supportedActionsChanged", a));
+			this.#state.on("textInputChanged", (s) => this.emit("textInputChanged", s));
+			this.#state.on("volumeAvailabilityChanged", (a) => this.emit("volumeAvailabilityChanged", a));
+			this.#state.subscribe();
+			await this.#state.fetchInitialState();
 		} catch (err) {
 			clearInterval(this.#heartbeatInterval);
 			this.#heartbeatInterval = void 0;
 			throw err;
 		}
 	}
-	async #subscribe() {
-		await this.#protocol.subscribe("SystemStatus", this.onSystemStatus);
-		await this.#protocol.subscribe("TVSystemStatus", this.onTVSystemStatus);
-		const state = await this.getAttentionState();
-		this.emit("power", state);
-	}
-	async #unsubscribe() {
-		try {
-			await this.#protocol.unsubscribe("SystemStatus", this.onSystemStatus);
-			await this.#protocol.unsubscribe("TVSystemStatus", this.onTVSystemStatus);
-		} catch (_) {}
+	/** Handles the stream close event. Emits 'disconnected' with unexpected=true if not intentional. */
+	onClose() {
+		this.#protocol.context.logger.net("onClose() called on companion link device.");
+		if (!this.#disconnect) {
+			this.disconnectSafely();
+			this.emit("disconnected", true);
+		} else this.emit("disconnected", false);
 	}
-	async onSystemStatus(data) {
-		this.#protocol.context.logger.info("System Status", data);
-		this.emit("power", convertAttentionState(data.state));
+	/**
+	* Handles stream error events by logging them.
+	*
+	* @param err - The error that occurred.
+	*/
+	onError(err) {
+		this.#protocol.context.logger.error("Companion Link error", err);
 	}
-	async onTVSystemStatus(data) {
-		this.#protocol.context.logger.info("TV System Status", data);
-		this.emit("power", convertAttentionState(data.state));
+	/** Handles stream timeout events by destroying the stream. */
+	onTimeout() {
+		this.#protocol.context.logger.error("Companion Link timeout");
+		this.#protocol.stream.destroy();
 	}
 };
 
 //#endregion
 //#region src/model/apple-tv.ts
+/**
+* High-level Apple TV device model combining AirPlay (remote control, media, streaming)
+* and Companion Link (apps, accounts, power, text input) protocols.
+* Provides a unified interface for controlling an Apple TV.
+*/
 var apple_tv_default = class extends EventEmitter {
+	/** The underlying AirPlay device for direct protocol access. */
 	get airplay() {
 		return this.#airplay;
 	}
+	/** The underlying Companion Link device for direct protocol access. */
 	get companionLink() {
 		return this.#companionLink;
 	}
+	/** AirPlay remote controller for HID keys and commands. */
 	get remote() {
 		return this.#airplay.remote;
 	}
+	/** AirPlay state tracker for now-playing, volume, and keyboard. */
 	get state() {
 		return this.#airplay.state;
 	}
+	/** AirPlay volume controller. */
 	get volumeControl() {
 		return this.#airplay.volume;
 	}
+	/** Bundle identifier of the currently playing app, or null. */
 	get bundleIdentifier() {
 		return this.#nowPlayingClient?.bundleIdentifier ?? null;
 	}
+	/** Display name of the currently playing app, or null. */
 	get displayName() {
 		return this.#nowPlayingClient?.displayName ?? null;
 	}
+	/** Whether both AirPlay and Companion Link are connected. */
 	get isConnected() {
 		return this.#airplay.isConnected && this.#companionLink.isConnected;
 	}
+	/** Whether the active player is currently playing. */
 	get isPlaying() {
 		return this.#nowPlayingClient?.isPlaying ?? false;
 	}
+	/** Current track title. */
 	get title() {
 		return this.#nowPlayingClient?.title ?? "";
 	}
+	/** Current track artist. */
 	get artist() {
 		return this.#nowPlayingClient?.artist ?? "";
 	}
+	/** Current track album. */
 	get album() {
 		return this.#nowPlayingClient?.album ?? "";
 	}
+	/** Duration of the current track in seconds. */
 	get duration() {
 		return this.#nowPlayingClient?.duration ?? 0;
 	}
+	/** Extrapolated elapsed time in seconds. */
 	get elapsedTime() {
 		return this.#nowPlayingClient?.elapsedTime ?? 0;
 	}
+	/** Current playback queue from the active player. */
 	get playbackQueue() {
 		return this.#nowPlayingClient?.playbackQueue ?? null;
 	}
+	/** Current playback state. */
 	get playbackState() {
 		return this.#nowPlayingClient?.playbackState ?? AirPlay.Proto.PlaybackState_Enum.Unknown;
 	}
+	/** Timestamp of the last playback state update. */
 	get playbackStateTimestamp() {
 		return this.#nowPlayingClient?.playbackStateTimestamp ?? -1;
 	}
+	/** Current volume level (0.0 - 1.0). */
 	get volume() {
 		return this.#airplay.state.volume ?? 0;
 	}
+	/** @returns The currently active now-playing client, or null. */
 	get #nowPlayingClient() {
 		return this.#airplay.state.nowPlayingClient;
 	}
 	#airplay;
 	#companionLink;
 	#disconnect = false;
+	/**
+	* Creates a new AppleTV instance.
+	*
+	* @param airplayDiscoveryResult - The mDNS discovery result for the AirPlay service.
+	* @param companionLinkDiscoveryResult - The mDNS discovery result for the Companion Link service.
+	*/
 	constructor(airplayDiscoveryResult, companionLinkDiscoveryResult) {
 		super();
 		this.#airplay = new device_default(airplayDiscoveryResult);
@@ -1254,81 +2778,170 @@ var apple_tv_default = class extends EventEmitter {
 		this.#airplay.on("disconnected", (unexpected) => this.#onDisconnected(unexpected));
 		this.#companionLink.on("connected", () => this.#onConnected());
 		this.#companionLink.on("disconnected", (unexpected) => this.#onDisconnected(unexpected));
-		this.#companionLink.on("power", (state) => this.emit("power", state));
-	}
+		this.#companionLink.on("attentionStateChanged", (state) => this.emit("power", state));
+		this.#companionLink.on("textInputChanged", (state) => this.emit("textInput", state));
+	}
+	/**
+	* Connects both AirPlay and Companion Link protocols.
+	* If Companion Link fails, AirPlay is disconnected to maintain consistency.
+	*
+	* @param airplayCredentials - Credentials for the AirPlay service.
+	* @param companionLinkCredentials - Optional separate credentials for Companion Link (defaults to AirPlay credentials).
+	*/
 	async connect(airplayCredentials, companionLinkCredentials) {
 		this.#airplay.setCredentials(airplayCredentials);
 		await this.#companionLink.setCredentials(companionLinkCredentials ?? airplayCredentials);
 		await this.#airplay.connect();
-		await this.#companionLink.connect();
+		try {
+			await this.#companionLink.connect();
+		} catch (err) {
+			this.#airplay.disconnectSafely();
+			throw err;
+		}
 		this.#disconnect = false;
 	}
+	/** Disconnects both AirPlay and Companion Link protocols. */
 	async disconnect() {
 		await this.#airplay.disconnect();
 		await this.#companionLink.disconnect();
 	}
+	/** Puts the Apple TV to sleep via a suspend HID key press. */
 	async turnOff() {
 		await this.#airplay.remote.suspend();
 	}
+	/** Wakes the Apple TV from sleep via a wake HID key press. */
 	async turnOn() {
 		await this.#airplay.remote.wake();
 	}
+	/** Sends a Pause command. */
 	async pause() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.Pause);
 	}
+	/** Sends a TogglePlayPause command. */
 	async playPause() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.TogglePlayPause);
 	}
+	/** Sends a Play command. */
 	async play() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.Play);
 	}
+	/** Sends a Stop command. */
 	async stop() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.Stop);
 	}
+	/** Sends a NextInContext command (next track/episode). */
 	async next() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.NextInContext);
 	}
+	/** Sends a PreviousInContext command (previous track/episode). */
 	async previous() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.PreviousInContext);
 	}
+	/** Decreases volume via HID volume down key. */
 	async volumeDown() {
 		await this.#airplay.remote.volumeDown();
 	}
+	/** Toggles mute via HID mute key. */
 	async volumeMute() {
 		await this.#airplay.remote.mute();
 	}
+	/** Increases volume via HID volume up key. */
 	async volumeUp() {
 		await this.#airplay.remote.volumeUp();
 	}
+	/**
+	* Fetches the current attention state via Companion Link.
+	*
+	* @returns The current attention state.
+	*/
 	async getAttentionState() {
 		return await this.#companionLink.getAttentionState();
 	}
+	/**
+	* Fetches the list of launchable apps via Companion Link.
+	*
+	* @returns Array of launchable app descriptors.
+	*/
 	async getLaunchableApps() {
 		return await this.#companionLink.getLaunchableApps();
 	}
+	/**
+	* Fetches user accounts configured on the device via Companion Link.
+	*
+	* @returns Array of user account descriptors.
+	*/
 	async getUserAccounts() {
 		return await this.#companionLink.getUserAccounts();
 	}
+	/**
+	* Launches an app via Companion Link.
+	*
+	* @param bundleId - The bundle identifier of the app to launch.
+	*/
 	async launchApp(bundleId) {
 		await this.#companionLink.launchApp(bundleId);
 	}
+	/**
+	* Switches user account via Companion Link.
+	*
+	* @param accountId - The ID of the user account to switch to.
+	*/
 	async switchUserAccount(accountId) {
 		await this.#companionLink.switchUserAccount(accountId);
 	}
+	/**
+	* Sets the text input field to the given text via Companion Link.
+	*
+	* @param text - The text to set.
+	*/
+	async textSet(text) {
+		await this.#companionLink.textSet(text);
+	}
+	/**
+	* Appends text to the text input field via Companion Link.
+	*
+	* @param text - The text to append.
+	*/
+	async textAppend(text) {
+		await this.#companionLink.textAppend(text);
+	}
+	/** Clears the text input field via Companion Link. */
+	async textClear() {
+		await this.#companionLink.textClear();
+	}
+	/**
+	* Gets the CommandInfo for a specific command from the active player.
+	*
+	* @param command - The command to look up.
+	* @returns The command info, or null if no client is active or command not found.
+	*/
 	async getCommandInfo(command) {
 		const client = this.#airplay.state.nowPlayingClient;
 		if (!client) return null;
 		return client.supportedCommands.find((c) => c.command === command) ?? null;
 	}
+	/**
+	* Checks whether a command is supported and enabled by the active player.
+	*
+	* @param command - The command to check.
+	* @returns True if supported and enabled, false otherwise.
+	*/
 	async isCommandSupported(command) {
 		const client = this.#airplay.state.nowPlayingClient;
 		if (!client) return false;
 		return client.isCommandSupported(command);
 	}
+	/** Emits 'connected' when both AirPlay and Companion Link are connected. */
 	async #onConnected() {
 		if (!this.#airplay.isConnected || !this.#companionLink.isConnected) return;
 		this.emit("connected");
 	}
+	/**
+	* Handles disconnection from either protocol. Disconnects both sides
+	* and emits 'disconnected'. Only fires once per disconnect cycle.
+	*
+	* @param unexpected - Whether the disconnection was unexpected.
+	*/
 	async #onDisconnected(unexpected) {
 		if (this.#disconnect) return;
 		this.#disconnect = true;
@@ -1339,110 +2952,187 @@ var apple_tv_default = class extends EventEmitter {
 
 //#endregion
 //#region src/model/homepod-base.ts
+/**
+* Abstract base class for HomePod models (HomePod and HomePod Mini).
+* Uses AirPlay only (no Companion Link). Supports transient pairing, media control,
+* URL playback, and audio streaming.
+*/
 var homepod_base_default = class extends EventEmitter {
+	/** The underlying AirPlay device for direct protocol access. */
 	get airplay() {
 		return this.#airplay;
 	}
+	/** AirPlay remote controller for HID keys and commands. */
 	get remote() {
 		return this.#airplay.remote;
 	}
+	/** AirPlay state tracker for now-playing and volume. */
 	get state() {
 		return this.#airplay.state;
 	}
+	/** AirPlay volume controller. */
 	get volumeControl() {
 		return this.#airplay.volume;
 	}
+	/** Bundle identifier of the currently playing app, or null. */
 	get bundleIdentifier() {
 		return this.#nowPlayingClient?.bundleIdentifier ?? null;
 	}
+	/** Display name of the currently playing app, or null. */
 	get displayName() {
 		return this.#nowPlayingClient?.displayName ?? null;
 	}
+	/** Whether the AirPlay connection is active. */
 	get isConnected() {
 		return this.#airplay.isConnected;
 	}
+	/** Whether the active player is currently playing. */
 	get isPlaying() {
 		return this.#nowPlayingClient?.isPlaying ?? false;
 	}
+	/** Current track title. */
 	get title() {
 		return this.#nowPlayingClient?.title ?? "";
 	}
+	/** Current track artist. */
 	get artist() {
 		return this.#nowPlayingClient?.artist ?? "";
 	}
+	/** Current track album. */
 	get album() {
 		return this.#nowPlayingClient?.album ?? "";
 	}
+	/** Duration of the current track in seconds. */
 	get duration() {
 		return this.#nowPlayingClient?.duration ?? 0;
 	}
+	/** Extrapolated elapsed time in seconds. */
 	get elapsedTime() {
 		return this.#nowPlayingClient?.elapsedTime ?? 0;
 	}
+	/** Current playback queue from the active player. */
 	get playbackQueue() {
 		return this.#nowPlayingClient?.playbackQueue ?? null;
 	}
+	/** Current playback state. */
 	get playbackState() {
 		return this.#nowPlayingClient?.playbackState ?? AirPlay.Proto.PlaybackState_Enum.Unknown;
 	}
+	/** Timestamp of the last playback state update. */
 	get playbackStateTimestamp() {
 		return this.#nowPlayingClient?.playbackStateTimestamp ?? -1;
 	}
+	/** Current volume level (0.0 - 1.0). */
 	get volume() {
 		return this.#airplay.state.volume ?? 0;
 	}
+	/** @returns The currently active now-playing client, or null. */
 	get #nowPlayingClient() {
 		return this.#airplay.state.nowPlayingClient;
 	}
 	#airplay;
 	#disconnect = false;
+	/**
+	* Creates a new HomePod base instance.
+	*
+	* @param discoveryResult - The mDNS discovery result for the AirPlay service.
+	*/
 	constructor(discoveryResult) {
 		super();
 		this.#airplay = new device_default(discoveryResult);
 		this.#airplay.on("connected", () => this.#onConnected());
 		this.#airplay.on("disconnected", (unexpected) => this.#onDisconnected(unexpected));
 	}
+	/** Connects to the HomePod via AirPlay (transient pairing). */
 	async connect() {
 		await this.#airplay.connect();
 		this.#disconnect = false;
 	}
+	/** Disconnects from the HomePod. */
 	async disconnect() {
 		await this.#airplay.disconnect();
 	}
+	/** Sends a Pause command. */
 	async pause() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.Pause);
 	}
+	/** Sends a TogglePlayPause command. */
 	async playPause() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.TogglePlayPause);
 	}
+	/** Sends a Play command. */
 	async play() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.Play);
 	}
+	/** Sends a Stop command. */
 	async stop() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.Stop);
 	}
+	/** Sends a NextInContext command (next track). */
 	async next() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.NextInContext);
 	}
+	/** Sends a PreviousInContext command (previous track). */
 	async previous() {
 		await this.#airplay.sendCommand(AirPlay.Proto.Command.PreviousInContext);
 	}
+	/**
+	* Plays a URL on the HomePod (the device fetches and plays the content).
+	*
+	* @param url - The media URL to play.
+	* @param position - Start position in seconds (defaults to 0).
+	*/
+	async playUrl(url, position = 0) {
+		await this.#airplay.playUrl(url, position);
+	}
+	/** Waits for the current URL playback to finish. */
+	async waitForPlaybackEnd() {
+		await this.#airplay.waitForPlaybackEnd();
+	}
+	/** Stops the current URL playback and cleans up. */
+	stopPlayUrl() {
+		this.#airplay.stopPlayUrl();
+	}
+	/**
+	* Streams audio from a source to the HomePod via RAOP/RTP.
+	*
+	* @param source - The audio source to stream.
+	*/
 	async streamAudio(source) {
 		await this.#airplay.streamAudio(source);
 	}
+	/**
+	* Gets the CommandInfo for a specific command from the active player.
+	*
+	* @param command - The command to look up.
+	* @returns The command info, or null if no client is active or command not found.
+	*/
 	async getCommandInfo(command) {
 		const client = this.#airplay.state.nowPlayingClient;
 		if (!client) return null;
 		return client.supportedCommands.find((c) => c.command === command) ?? null;
 	}
+	/**
+	* Checks whether a command is supported and enabled by the active player.
+	*
+	* @param command - The command to check.
+	* @returns True if supported and enabled, false otherwise.
+	*/
 	async isCommandSupported(command) {
 		const client = this.#airplay.state.nowPlayingClient;
 		if (!client) return false;
 		return client.isCommandSupported(command);
 	}
+	/** Emits 'connected' when the AirPlay connection is established. */
 	async #onConnected() {
 		this.emit("connected");
 	}
+	/**
+	* Handles disconnection. Disconnects and emits 'disconnected'.
+	* Only fires once per disconnect cycle.
+	*
+	* @param unexpected - Whether the disconnection was unexpected.
+	*/
 	async #onDisconnected(unexpected) {
 		if (this.#disconnect) return;
 		this.#disconnect = true;
@@ -1453,10 +3143,18 @@ var homepod_base_default = class extends EventEmitter {
 
 //#endregion
 //#region src/model/homepod.ts
+/**
+* HomePod device model. AirPlay only (no Companion Link).
+* Supports media control, URL playback, audio streaming, and volume control.
+*/
 var homepod_default = class extends homepod_base_default {};
 
 //#endregion
 //#region src/model/homepod-mini.ts
+/**
+* HomePod Mini device model. AirPlay only (no Companion Link).
+* Identical feature set to HomePod, distinguished for device model identification.
+*/
 var homepod_mini_default = class extends homepod_base_default {};
 
 //#endregion